|
| 1 | +#!/usr/bin/env python3 |
| 2 | +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 3 | +# SPDX-License-Identifier: Apache-2.0 |
| 4 | + |
| 5 | +# /// script |
| 6 | +# requires-python = ">=3.9" |
| 7 | +# dependencies = [ |
| 8 | +# "PyYAML==6.0.2", |
| 9 | +# ] |
| 10 | +# /// |
| 11 | + |
| 12 | +"""Check that the published docs navigation mirrors the docs folder structure. |
| 13 | +
|
| 14 | +Fern does not build page URLs from file paths. It uses, in order, the page's |
| 15 | +frontmatter `slug`, the nav entry's `slug`, or the nav label, and it splits |
| 16 | +camel case in labels, so "TypeScript" becomes `type-script`. Pages in a |
| 17 | +`folder:` section use their file names. A URL can therefore drift away from |
| 18 | +where its file lives without any link breaking. |
| 19 | +
|
| 20 | +This check fails when: |
| 21 | +
|
| 22 | +- a page's URL differs from its file path under docs/, without `.mdx`, and |
| 23 | + without `/index` for a section's own page; |
| 24 | +- a nav page's sidebar name, its `sidebar-title` or else its `title`, differs |
| 25 | + from its nav label. Fern shows the sidebar name but builds the URL from the |
| 26 | + label, so the two must agree; |
| 27 | +- a docs page is not reachable from the navigation; or |
| 28 | +- a redirect for this docs version points to a URL that does not exist, or its |
| 29 | + source is still a live page. |
| 30 | +""" |
| 31 | + |
| 32 | +from __future__ import annotations |
| 33 | + |
| 34 | +import argparse |
| 35 | +import re |
| 36 | +import sys |
| 37 | +from dataclasses import dataclass, field |
| 38 | +from pathlib import Path |
| 39 | + |
| 40 | +import yaml |
| 41 | + |
| 42 | +# Files under docs/ that are intentionally not published as pages. |
| 43 | +UNPUBLISHED = {"CONTRIBUTING.mdx"} |
| 44 | + |
| 45 | + |
| 46 | +def fern_slug(label: str) -> str: |
| 47 | + """Slugify a nav label the way Fern does, including camel-case splits.""" |
| 48 | + split = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", label) |
| 49 | + return re.sub(r"[^a-z0-9]+", "-", split.lower()).strip("-") |
| 50 | + |
| 51 | + |
| 52 | +def path_url(rel_path: str) -> str: |
| 53 | + """Return the URL that a docs file path implies.""" |
| 54 | + url = "/" + re.sub(r"\.mdx$", "", rel_path) |
| 55 | + return re.sub(r"/index$", "", url) |
| 56 | + |
| 57 | + |
| 58 | +def frontmatter(path: Path) -> dict: |
| 59 | + match = re.match(r"---\n(.*?)\n---", path.read_text(encoding="utf-8"), re.S) |
| 60 | + if not match: |
| 61 | + return {} |
| 62 | + return yaml.safe_load(match.group(1)) or {} |
| 63 | + |
| 64 | + |
| 65 | +@dataclass |
| 66 | +class NavCheck: |
| 67 | + docs_root: Path |
| 68 | + urls: dict[str, str] = field(default_factory=dict) # URL -> docs-relative path |
| 69 | + reachable: set[str] = field(default_factory=set) |
| 70 | + issues: list[str] = field(default_factory=list) |
| 71 | + |
| 72 | + def page_url(self, rel_path: str, default_url: str) -> str: |
| 73 | + slug = frontmatter(self.docs_root / rel_path).get("slug") |
| 74 | + return "/" + str(slug).strip("/") if slug else default_url |
| 75 | + |
| 76 | + def record(self, rel_path: str, url: str, how: str) -> None: |
| 77 | + self.reachable.add(rel_path) |
| 78 | + if url in self.urls and self.urls[url] != rel_path: |
| 79 | + self.issues.append( |
| 80 | + f"{rel_path}: URL {url} is also used by {self.urls[url]}" |
| 81 | + ) |
| 82 | + self.urls[url] = rel_path |
| 83 | + expected = path_url(rel_path) |
| 84 | + if url != expected: |
| 85 | + self.issues.append( |
| 86 | + f"{rel_path}: URL {url} ({how}) does not match its file path " |
| 87 | + f"{expected}. Rename the file, change the nav label, or set " |
| 88 | + f'frontmatter slug: "{expected.lstrip("/")}".' |
| 89 | + ) |
| 90 | + |
| 91 | + def walk(self, items: list, prefix: str) -> None: |
| 92 | + for item in items or []: |
| 93 | + if "section" in item: |
| 94 | + url = prefix + "/" + item.get("slug", fern_slug(item["section"])) |
| 95 | + if "path" in item: |
| 96 | + rel = item["path"] |
| 97 | + self.record(rel, self.page_url(rel, url), "section page") |
| 98 | + self.walk(item.get("contents", []), url) |
| 99 | + elif "page" in item: |
| 100 | + rel, label = item["path"], item["page"] |
| 101 | + if not (self.docs_root / rel).exists(): |
| 102 | + self.issues.append( |
| 103 | + f"docs/index.yml: nav page {label!r} points to missing {rel}" |
| 104 | + ) |
| 105 | + continue |
| 106 | + if "slug" in item: |
| 107 | + default, how = prefix + "/" + item["slug"], "nav slug" |
| 108 | + else: |
| 109 | + default, how = ( |
| 110 | + prefix + "/" + fern_slug(label), |
| 111 | + f"nav label {label!r}", |
| 112 | + ) |
| 113 | + meta = frontmatter(self.docs_root / rel) |
| 114 | + how = "frontmatter slug" if meta.get("slug") else how |
| 115 | + self.record(rel, self.page_url(rel, default), how) |
| 116 | + shown_key = "sidebar-title" if "sidebar-title" in meta else "title" |
| 117 | + shown = meta.get(shown_key) |
| 118 | + if shown != label: |
| 119 | + self.issues.append( |
| 120 | + f"{rel}: {shown_key} {shown!r} does not match nav label {label!r}" |
| 121 | + ) |
| 122 | + elif "folder" in item: |
| 123 | + folder = item["folder"].strip("./").rstrip("/") |
| 124 | + url = ( |
| 125 | + prefix |
| 126 | + + "/" |
| 127 | + + item.get("slug", fern_slug(item.get("title", folder))) |
| 128 | + ) |
| 129 | + for page in sorted((self.docs_root / folder).rglob("*.mdx")): |
| 130 | + rel = page.relative_to(self.docs_root).as_posix() |
| 131 | + stem = ( |
| 132 | + page.relative_to(self.docs_root / folder) |
| 133 | + .with_suffix("") |
| 134 | + .as_posix() |
| 135 | + ) |
| 136 | + default = re.sub(r"/index$", "", url + "/" + stem) |
| 137 | + how = ( |
| 138 | + "frontmatter slug" |
| 139 | + if frontmatter(page).get("slug") |
| 140 | + else "folder file name" |
| 141 | + ) |
| 142 | + self.record(rel, self.page_url(rel, default), how) |
| 143 | + |
| 144 | + def check_orphans(self) -> None: |
| 145 | + for page in sorted(self.docs_root.rglob("*.mdx")): |
| 146 | + rel = page.relative_to(self.docs_root).as_posix() |
| 147 | + if rel in UNPUBLISHED or rel in self.reachable or rel.startswith("_"): |
| 148 | + continue |
| 149 | + self.issues.append(f"{rel}: not reachable from docs/index.yml") |
| 150 | + |
| 151 | + def check_redirects(self, redirects: list, prefix: str) -> None: |
| 152 | + live = set(self.urls) | {""} |
| 153 | + for redirect in redirects or []: |
| 154 | + source, dest = redirect.get("source", ""), redirect.get("destination", "") |
| 155 | + if dest.startswith(prefix + "/") or dest == prefix: |
| 156 | + target = dest[len(prefix) :].split("#", 1)[0].rstrip("/") |
| 157 | + if ":" not in target and target not in live: |
| 158 | + self.issues.append( |
| 159 | + f"fern/docs.yml: redirect {source} -> {dest}: destination does not exist" |
| 160 | + ) |
| 161 | + if source.startswith(prefix + "/") and ":" not in source: |
| 162 | + origin = source[len(prefix) :].rstrip("/") |
| 163 | + if origin in live: |
| 164 | + self.issues.append( |
| 165 | + f"fern/docs.yml: redirect source {source} is still a live page" |
| 166 | + ) |
| 167 | + |
| 168 | + |
| 169 | +def redirect_prefix(fern_config: dict, nav_file: Path, config_dir: Path) -> str | None: |
| 170 | + """Return the URL prefix, such as /openshell/dev, for the checked docs version.""" |
| 171 | + instances = fern_config.get("instances") or [] |
| 172 | + url = instances[0].get("url", "") if instances else "" |
| 173 | + base = "/" + url.split("/", 1)[1].strip("/") if "/" in url else "" |
| 174 | + for version in fern_config.get("versions") or []: |
| 175 | + if (config_dir / version.get("path", "")).resolve() == nav_file.resolve(): |
| 176 | + return f"{base}/{version['slug']}".replace("//", "/") |
| 177 | + return None |
| 178 | + |
| 179 | + |
| 180 | +def run(repo_root: Path) -> list[str]: |
| 181 | + docs_root = repo_root / "docs" |
| 182 | + nav_file = docs_root / "index.yml" |
| 183 | + nav = yaml.safe_load(nav_file.read_text(encoding="utf-8")) |
| 184 | + check = NavCheck(docs_root) |
| 185 | + landing = (nav.get("landing-page") or {}).get("path") |
| 186 | + if landing: |
| 187 | + check.reachable.add(landing) |
| 188 | + check.walk(nav.get("navigation", []), "") |
| 189 | + check.check_orphans() |
| 190 | + fern_file = repo_root / "fern" / "docs.yml" |
| 191 | + if fern_file.exists(): |
| 192 | + fern_config = yaml.safe_load(fern_file.read_text(encoding="utf-8")) |
| 193 | + prefix = redirect_prefix(fern_config, nav_file, fern_file.parent) |
| 194 | + if prefix: |
| 195 | + check.check_redirects(fern_config.get("redirects"), prefix) |
| 196 | + return check.issues |
| 197 | + |
| 198 | + |
| 199 | +def main() -> int: |
| 200 | + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) |
| 201 | + parser.add_argument( |
| 202 | + "--repo-root", type=Path, default=Path(__file__).resolve().parents[2] |
| 203 | + ) |
| 204 | + args = parser.parse_args() |
| 205 | + issues = run(args.repo_root) |
| 206 | + for issue in issues: |
| 207 | + print(f"docs nav: {issue}", file=sys.stderr) |
| 208 | + if issues: |
| 209 | + print(f"docs nav: {len(issues)} problem(s) found", file=sys.stderr) |
| 210 | + return 1 |
| 211 | + print("docs nav: every page URL matches its file path") |
| 212 | + return 0 |
| 213 | + |
| 214 | + |
| 215 | +if __name__ == "__main__": |
| 216 | + sys.exit(main()) |
0 commit comments