refactor(docs-autogen): remove stale Mintlify references from tooling

Four stale Mintlify-era references flagged by @ajbozarth in review:

- audit_coverage.py: error hint for missing symbols now points to
  docs/sidebars.ts (replaces obsolete docs/docs/docs.json reference)
- generate-ast.py: update module docstring, rename tree_to_mintlify
  -> tree_to_nav, update argparse help text
- decorate_api_mdx.py: update SidebarFix comment and --docs-root
  help text
- check_docs.py: rename file_exists_mintlify -> file_exists_docs,
  update link-check description and diagnostic strings

Signed-off-by: Nigel Jones <jonesn@uk.ibm.com>
Assisted-by: Claude Code

Author: planetf1

docs/scripts/check_docs.py

@@ -16,15 +16,14 @@
 Link checks
 -----------
 * Internal doc-to-doc links (relative paths within docs/docs/).
-* Mintlify absolute paths (/getting-started/installation etc.) resolved
-  against docs/docs/ and docs.json navigation.
-* Mintlify Card href="..." attributes (JSX).
+* Absolute paths (/getting-started/installation etc.) resolved
+  against docs/docs/.
+* Card href="..." attributes (JSX).
 * Links that escape docs/docs/ (e.g. ../../examples/) — these resolve
-  on the local filesystem but NOT on the published Mintlify site.  They
+  on the local filesystem but NOT on the published docs site.  They
   are flagged as errors: use a full GitHub URL instead.
 * External URLs (https://) — checked with a lightweight HEAD request.
   Failures are reported as warnings (network-dependent).
-* docs.json navbar links and nav page slugs.
 
 Code checks
 -----------
@@ -66,7 +65,7 @@
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 REPO_ROOT = SCRIPT_DIR.parent.parent  # docs/scripts/../../
-DOCS_ROOT = REPO_ROOT / "docs" / "docs"  # Mintlify content root
+DOCS_ROOT = REPO_ROOT / "docs" / "docs"  # docs content root
 
 # Skip API reference pages (separate PR)
 SKIP_PREFIXES = ("api/",)
@@ -129,8 +128,8 @@ def strip_anchor(target: str) -> str:
     return target.split("#", 1)[0]
 
 
-def file_exists_mintlify(resolved: Path) -> bool:
-    """Check whether the resolved target exists, trying Mintlify
+def file_exists_docs(resolved: Path) -> bool:
+    """Check whether the resolved target exists, trying standard
     extension conventions (.md, .mdx, index files)."""
     if resolved.exists():
         return True
@@ -278,7 +277,7 @@ def run_link_checks(
                     continue
 
                 resolved = DOCS_ROOT / target_clean.lstrip("/")
-                if file_exists_mintlify(resolved):
+                if file_exists_docs(resolved):
                     if verbose:
                         print(f"  [ok]   {rel}:{lineno} -> {raw_target}")
                 else:
@@ -302,7 +301,7 @@ def run_link_checks(
             if not inside_docs:
                 # It might still exist in the repo...
                 if resolved.exists() or Path(str(resolved)).exists():
-                    # File exists in repo but won't work on Mintlify site
+                    # File exists in repo but escapes the docs root
                     # Suggest the GitHub URL
                     try:
                         repo_rel = resolved.relative_to(REPO_ROOT)
@@ -311,7 +310,7 @@ def run_link_checks(
                         suggested = "(could not compute GitHub URL)"
                     errors.append(
                         f"  {rel}:{lineno} -> {raw_target}"
-                        f"  [escapes docs/ — won't work on Mintlify."
+                        f"  [escapes docs/ — won't resolve on published site."
                         f" Suggest: {suggested}]"
                     )
                 else:
@@ -324,7 +323,7 @@ def run_link_checks(
                 continue
 
             # Normal internal link
-            if file_exists_mintlify(resolved):
+            if file_exists_docs(resolved):
                 if verbose:
                     print(f"  [ok]   {rel}:{lineno} -> {raw_target}")
             else:
@@ -336,7 +335,7 @@ def run_link_checks(
         if any(slug.startswith(pfx) for pfx in SKIP_PREFIXES):
             continue
         resolved = DOCS_ROOT / slug
-        if not file_exists_mintlify(resolved):
+        if not file_exists_docs(resolved):
             errors.append(f"  docs.json nav: '{slug}' — file not found")
         elif verbose:
             print(f"  [ok]   docs.json nav: {slug}")

tooling/docs-autogen/audit_coverage.py

@@ -1053,7 +1053,7 @@ def main():
         )
         print(
             "  Fix: Run the doc generation pipeline to produce MDX for new symbols,\n"
-            "       then add entries to docs/docs/docs.json navigation.\n"
+            "       then add entries to docs/sidebars.ts.\n"
             "       uv run python tooling/docs-autogen/generate-ast.py"
         )
         print(f"  Ref: {_COVERAGE_DOCS_URL}")

tooling/docs-autogen/decorate_api_mdx.py

@@ -850,7 +850,7 @@ def process_mdx_file(
     text = inject_preamble(text, module_path, docstring_cache)
     text = normalize_rst_backticks(text)
 
-    # Step 3: SidebarFix injection disabled (Mintlify-only; site now uses Docusaurus)
+    # Step 3: SidebarFix injection disabled (was Mintlify-only; no-op on Docusaurus)
 
     # Step 3.5: Wrap bare doctest (>>>) blocks in fenced code blocks.
     # Must run before escape_mdx_syntax so the new fences are processed.
@@ -875,7 +875,7 @@ def process_mdx_file(
 def main() -> None:
     parser = argparse.ArgumentParser(description="Decorate API MDX files")
     parser.add_argument(
-        "--docs-root", type=Path, default=None, help="Mintlify docs root directory"
+        "--docs-root", type=Path, default=None, help="Docs root directory"
     )
     parser.add_argument(
         "--api-dir", type=Path, default=None, help="API directory containing MDX files"

tooling/docs-autogen/generate-ast.py

@@ -2,7 +2,7 @@
 """generate-ast.py — mdxify + postprocess docs pipeline.
 
 Runs mdxify against the project's mellea package then postprocesses
-the generated MDX files into the Mintlify docs tree.
+the generated MDX files into the Docusaurus docs tree.
 
 Requires mdxify to be installed in the current Python environment.  Run via::
 
@@ -15,8 +15,7 @@
   4) Update frontmatter (title/sidebarTitle/description) from H1 + first paragraph
   5) Remove truly-empty MDX files
   6) Move generated docs to <docs-root>/api (replace existing)
-  7) Build Mintlify API Reference nav (NO .mdx suffix)
-  8) Merge by replacing ONLY: { "tab": "API Reference", ... } in docs.json
+  7) Build API Reference nav tree (docs.json merge skipped in Docusaurus mode)
 """
 
 import argparse
@@ -583,14 +582,14 @@ def insert(node: dict[str, Any], parts: list[str], page_path: str) -> None:
     return root
 
 
-def tree_to_mintlify(node: dict[str, Any], group_name: str) -> dict[str, Any]:
+def tree_to_nav(node: dict[str, Any], group_name: str) -> dict[str, Any]:
     pages: list[Any] = []
     file_pages = node.get("__pages__", [])
     if file_pages:
         pages.extend(sorted(file_pages))
 
     for k in sorted(x for x in node.keys() if x != "__pages__"):
-        pages.append(tree_to_mintlify(node[k], k))
+        pages.append(tree_to_nav(node[k], k))
 
     return {"group": group_name, "pages": pages}
 
@@ -785,7 +784,7 @@ def build_api_reference_tab_object(api_dir: Path, docs_root: Path) -> dict[str,
     mellea_pages = collect_pages_under(api_dir, "mellea", docs_root)
 
     mellea_tree = build_tree_from_paths(mellea_pages)
-    mellea_nav = tree_to_mintlify(mellea_tree, "mellea")
+    mellea_nav = tree_to_nav(mellea_tree, "mellea")
 
     return {
         "tab": NAV_TAB,
@@ -852,15 +851,17 @@ def build_and_merge_navigation(
 # -----------------------------
 def main() -> None:
     parser = argparse.ArgumentParser(
-        description="Generate MDX API docs with mdxify, postprocess, and merge into the Mintlify docs tree."
+        description="Generate MDX API docs with mdxify, postprocess, and merge into the Docusaurus docs tree."
     )
     parser.add_argument(
-        "--docs-json", required=False, help="Path to docs.json to update."
+        "--docs-json",
+        required=False,
+        help="Path to docs.json to update (legacy; ignored in Docusaurus mode).",
     )
     parser.add_argument(
         "--docs-root",
         required=False,
-        help="Mintlify docs root (defaults to parent of docs.json).",
+        help="Docs root directory (defaults to parent of docs.json).",
     )
     parser.add_argument(
         "--nav-only",