deruyter92 · Sep 17, 2026 · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026 · Jul 16, 2026
diff --git a/pyproject.toml b/pyproject.toml
@@ -180,9 +180,11 @@ gui-dev = [
   "pytest-qt",
 ]
 knowledge-index = [
-  "docutils",
-  "griffelib",
-  "markdown-it-py",
+  # Keep these aligned with the majors the docs toolchain resolves to:
+  # ids, anchors, signatures and symbol kinds are derived through them.
+  "docutils>=0.20,<0.22",
+  "griffelib>=2,<3",
+  "markdown-it-py>=3,<4",
   "pyyaml",
 ]
 

diff --git a/tests/tools/knowledge_indexing/test_api_index.py b/tests/tools/knowledge_indexing/test_api_index.py
@@ -96,3 +96,14 @@ def test_the_class_itself_is_still_recorded(nodes):
     symbols = _symbols(nodes, "demopkg.thing")
 
     assert symbols["Thing"].kind == "class"
+
+
+def test_root_reexports_are_indexed_on_the_package(nodes):
+    # Public API is re-exported from the package root; URLs must stay on that page.
+    symbols = _symbols(nodes, "demopkg")
+
+    assert symbols["Thing"].kind == "class"
+    assert symbols["Thing"].docs_url == ("https://example.test/reference/demopkg/thing/#demopkg.thing.Thing")
+    # A re-exported class's methods follow the class, not the re-exporting page,
+    # while keeping the name the caller reaches them under.
+    assert symbols["Thing.run"].docs_url == ("https://example.test/reference/demopkg/thing/#demopkg.thing.Thing.run")
diff --git a/tests/tools/knowledge_indexing/test_docs_index.py b/tests/tools/knowledge_indexing/test_docs_index.py
@@ -8,7 +8,9 @@
 from tools.knowledge_indexing.docs_index import (
     _page_anchors,
     _read_structure,
+    _resolve_target,
     _split_frontmatter,
+    build_docs_nodes,
     read_published_anchors,
 )
 from tools.knowledge_indexing.toc import TocEntry
@@ -99,6 +101,20 @@ def test_page_title_h1_does_not_consume_a_later_heading_s_occurrence():
     assert section.anchor == "overview"
 
 
+def test_heading_without_section_id_still_advances_occurrence():
+    # A titled heading with no usable section id must still count, or the next
+    # repeat of that title would resolve to the wrong published anchor.
+    html = """
+    <section id=""><h2>Overview</h2></section>
+    <section id="id1"><h2>Overview</h2></section>
+    """
+    markdown = "# Title\n\n## Overview\n\nA.\n\n## Overview\n\nB.\n"
+    first, second = _sections(markdown, read_published_anchors(html))
+
+    assert first.anchor == ""
+    assert second.anchor == "id1"
+
+
 def test_only_the_first_h1_is_the_page_title():
     # Some pages use h1 throughout, so only the first may be taken as the title.
     sections = _sections("# Title\n\nLead.\n\n# Second\n\nA.\n\n# Third\n\nB.\n")
@@ -179,3 +195,46 @@ def test_malformed_yaml_keeps_the_page_whole():
 def test_page_without_frontmatter_is_unchanged():
     text = "# Title\n\nProse.\n"
     assert _split_frontmatter(text) == ({}, text)
+
+
+@pytest.mark.parametrize(
+    ("target", "directory", "labels", "expected"),
+    [
+        ("file:install", "docs", {"file:install": "installation", "install": "installation"}, "installation"),
+        ("install", "docs", {"file:install": "installation", "install": "installation"}, "installation"),
+        ("../sibling.md", "docs/guide", {}, "sibling"),
+        ("https://example.test/x", "docs", {}, ""),
+        ("#only-anchor", "docs", {}, ""),
+        ("../../escape.md", "docs", {}, ""),
+        ("image.png", "docs", {}, ""),
+        ("unknown-label", "docs", {}, ""),
+    ],
+)
+def test_resolve_target(target, directory, labels, expected):
+    assert _resolve_target(target, directory, labels) == expected
+
+
+def test_build_docs_nodes_skips_hidden_and_resolves_related(tmp_path: Path):
+    (tmp_path / "_toc.yml").write_text(
+        "format: jb-book\nroot: docs/a\nchapters:\n  - file: docs/b\n  - file: docs/hidden\n  - file: docs/orphan\n",
+        encoding="utf-8",
+    )
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    (docs / "a.md").write_text(
+        "# A\n\nSee {ref}`file:b-page` and [B](b.md).\n\n(file:a-page)=\n",
+        encoding="utf-8",
+    )
+    (docs / "b.md").write_text("# B\n\nProse.\n\n(file:b-page)=\n", encoding="utf-8")
+    (docs / "hidden.md").write_text(
+        "---\ndeeplabcut:\n  ignore: true\n---\n# Hidden\n",
+        encoding="utf-8",
+    )
+    (docs / "orphan.md").write_text(
+        "---\ndeeplabcut:\n  visibility: orphaned\n---\n# Orphan\n",
+        encoding="utf-8",
+    )
+
+    nodes = {node.id: node for node in build_docs_nodes(tmp_path)}
+    assert set(nodes) == {"docs:a", "docs:b"}
+    assert nodes["docs:a"].related_pages == ("docs:b",)
diff --git a/tests/tools/knowledge_indexing/test_llms_txt.py b/tests/tools/knowledge_indexing/test_llms_txt.py
@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from tools.knowledge_indexing.__main__ import API_BASE_URL, DOCS_VERSION_LABEL, LLMS_TXT, PACKAGE, main
+from tools.knowledge_indexing.llms_txt import build_llms_txt
+from tools.knowledge_indexing.schemas import LATEST_RELEASE_ALIAS
+
+
+def test_llms_txt_lists_stable_and_rolling_api_links():
+    # The urls are landing pages, carrying the package segment: api-autonav
+    # publishes no index at `reference/`, so a link to it 404s.
+    text = build_llms_txt(
+        docs_base_url="https://example.test/",
+        stable_api_reference_url="https://example.test/dev/latest-release/reference/deeplabcut/",
+        rolling_api_reference_url="https://example.test/dev/main/reference/deeplabcut/",
+        knowledge_base_url="https://example.test/knowledge/",
+        version_label="main",
+    )
+
+    assert "- [API reference (stable release)](https://example.test/dev/latest-release/reference/deeplabcut/)" in text
+    assert "- [API reference (main / unreleased)](https://example.test/dev/main/reference/deeplabcut/)" in text
+
+
+def test_llms_txt_keeps_machine_readable_links_version_scoped():
+    text = build_llms_txt(
+        docs_base_url="https://example.test/",
+        stable_api_reference_url="https://example.test/dev/latest-release/reference/deeplabcut/",
+        rolling_api_reference_url="https://example.test/dev/main/reference/deeplabcut/",
+        knowledge_base_url="https://example.test/knowledge/",
+        version_label="3.0",
+    )
+
+    assert "https://example.test/knowledge/3.0/docs.jsonl" in text
+    assert "https://example.test/knowledge/3.0/api.jsonl" in text
+
+
+def test_cli_points_each_api_link_at_the_right_deploy(tmp_path: Path):
+    # The unit tests above are handed both urls, so they cannot catch the two
+    # being swapped or built from the wrong label in `__main__.py`.
+    (tmp_path / "_toc.yml").write_text("format: jb-book\nroot: README\n", encoding="utf-8")
+    (tmp_path / "README.md").write_text("# DeepLabCut\n\nLead.\n", encoding="utf-8")
+    package = tmp_path / PACKAGE
+    package.mkdir()
+    (package / "__init__.py").write_text('"""Package."""\n', encoding="utf-8")
+
+    output = tmp_path / "out"
+    assert main(["--output", str(output), "--repo", str(tmp_path), "--revision", "abc123"]) == 0
+
+    link = re.compile(r"^- \[(?P<label>[^\]]+)\]\((?P<url>[^)]+)\)")
+    lines = {
+        m["label"]: m["url"]
+        for m in (link.match(line) for line in (output / LLMS_TXT).read_text(encoding="utf-8").splitlines())
+        if m and m["label"].startswith("API reference")
+    }
+    reference = f"reference/{PACKAGE}/"
+    assert lines["API reference (stable release)"] == (
+        f"{API_BASE_URL.format(version=LATEST_RELEASE_ALIAS)}{reference}"
+    )
+    assert lines["API reference (main / unreleased)"] == (
+        f"{API_BASE_URL.format(version=DOCS_VERSION_LABEL)}{reference}"
+    )
diff --git a/tests/tools/knowledge_indexing/test_mkdocs_sync.py b/tests/tools/knowledge_indexing/test_mkdocs_sync.py
@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from tools.knowledge_indexing.api_index import API_ROOT_URI, EXCLUDED_MODULES
+
+
+def test_constants_match_the_dev_docs_config():
+    # These mirror plugins.api-autonav in dev-docs/mkdocs.yml. Drift there
+    # silently repoints every generated api url at a page that does not exist.
+    config = yaml.safe_load((Path(__file__).resolve().parents[3] / "dev-docs/mkdocs.yml").read_text(encoding="utf-8"))
+    autonav = next(p["api-autonav"] for p in config["plugins"] if isinstance(p, dict) and "api-autonav" in p)
+
+    assert autonav["api_root_uri"] == API_ROOT_URI
+    assert tuple(autonav["exclude"]) == EXCLUDED_MODULES
diff --git a/tests/tools/knowledge_indexing/test_write.py b/tests/tools/knowledge_indexing/test_write.py
@@ -19,6 +19,7 @@
 from tools.knowledge_indexing.write import (
     _check_unique_ids,
     _read_json,
+    _write_jsonl,
     delete_version,
     write_top_manifest,
     write_version,
@@ -85,6 +86,14 @@ def test_check_unique_ids_raises_on_duplicate():
         _check_unique_ids("api.jsonl", ["a", "b", "a"])
 
 
+def test_empty_jsonl_is_an_empty_file(tmp_path: Path):
+    path = tmp_path / "empty.jsonl"
+    _write_jsonl(path, ())
+    # A trailing blank line would break `json.loads(line)` without filtering.
+    assert path.read_text(encoding="utf-8") == ""
+    assert [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines()] == []
+
+
 def test_read_json_missing_returns_none(tmp_path: Path):
     assert _read_json(tmp_path / "missing.json") is None
 
@@ -150,6 +159,13 @@ def test_write_version_skip_keeps_existing_half(tmp_path: Path):
     assert second["docs"]["revision"] == "second"
 
 
+def test_skipping_api_without_existing_provenance_leaves_no_directory(tmp_path: Path):
+    knowledge_dir = tmp_path / KNOWLEDGE_DIR
+    with pytest.raises(ValueError, match="No api provenance"):
+        write_version(knowledge_dir, "3.0", None, _sample_docs(), revision="r1")
+    assert not (knowledge_dir / "3.0").exists()
+
+
 def test_write_top_manifest_and_delete_version(tmp_path: Path):
     knowledge_dir = tmp_path / KNOWLEDGE_DIR
     write_version(knowledge_dir, "main", _sample_api(), _sample_docs(), revision="r1")
@@ -303,3 +319,13 @@ def test_delete_main_via_cli_refused(tmp_path: Path, capsys):
     assert code == 1
     assert "cannot be deleted" in capsys.readouterr().err
     assert (knowledge_dir / "main").is_dir()
+
+
+def test_skip_api_on_non_main_is_rejected(tmp_path: Path, capsys):
+    # Docs are only indexed for main, so --skip-api on another label leaves
+    # nothing to do and must not report success.
+    from tools.knowledge_indexing.__main__ import main
+
+    code = main(["--version-label", "3.0", "--skip-api", "--output", str(tmp_path)])
+    assert code == 1
+    assert "nothing to do" in capsys.readouterr().err
diff --git a/tools/knowledge_indexing/README.md b/tools/knowledge_indexing/README.md
@@ -109,6 +109,10 @@ methods, attributes and properties are not recorded.
 
 Two constants in `api_index.py` mirror `dev-docs/mkdocs.yml` and must be kept in
 sync with it: `EXCLUDED_MODULES` and `API_ROOT_URI`.
+The `knowledge-index` dependency-group bounds in `pyproject.toml` are the same
+kind of coupling: griffe, docutils and markdown-it-py must stay on majors that
+match the docs toolchain, or published signatures, symbol kinds and section ids
+can drift without any source change.
 
 ### Docs pages
 
@@ -166,9 +170,13 @@ explicit `ignore: true`.
 Written only for `--version-label main`, alongside `docs.jsonl`. Follows the
 [llmstxt.org](https://llmstxt.org) convention: an H1 title, a one-line
 description, then `##` sections of links.
-Links to the docs site, the API reference, and prominently to
-`knowledge/manifest.json`, `docs.jsonl` and `api.jsonl` for agents that want
-the structured index.
+Links to the docs site, both the stable-release and rolling-main API
+reference, and prominently to `knowledge/manifest.json`, `docs.jsonl` and
+`api.jsonl` for agents that want the structured index.
+
+The stable link points at mike's `latest-release` alias rather than at
+`--version-label`: only the `main` build writes `llms.txt`, so the label would
+aim it at the rolling unreleased API (see "Versioning").
 
 ## Deployment
 

diff --git a/tools/knowledge_indexing/__main__.py b/tools/knowledge_indexing/__main__.py
@@ -186,8 +186,14 @@ def main(argv: list[str] | None = None) -> int:
     args = _parse_args(argv)
     repo: Path = args.repo
 
-    if args.skip_api and args.skip_docs:
-        print("Error: --skip-api and --skip-docs together leave nothing to do.", file=sys.stderr)
+    include_api = not args.skip_api
+    include_docs = args.version_label == DOCS_VERSION_LABEL and not args.skip_docs
+    if not args.delete and not include_api and not include_docs:
+        docs_reason = "--skip-docs" if args.skip_docs else f"docs are only indexed for '{DOCS_VERSION_LABEL}'"
+        print(
+            f"Error: nothing to do for version {args.version_label!r}: --skip-api, and {docs_reason}.",
+            file=sys.stderr,
+        )
         return 1
 
     if args.delete and (args.skip_api or args.skip_docs):
@@ -218,8 +224,8 @@ def main(argv: list[str] | None = None) -> int:
         return 1
 
     api_base_url = API_BASE_URL.format(version=args.version_label)
-    include_api = not args.skip_api
-    include_docs = args.version_label == DOCS_VERSION_LABEL and not args.skip_docs
+    stable_api_reference_url = f"{API_BASE_URL.format(version=LATEST_RELEASE_ALIAS)}reference/{PACKAGE}/"
+    rolling_api_reference_url = f"{API_BASE_URL.format(version=DOCS_VERSION_LABEL)}reference/{PACKAGE}/"
 
     apis = None
     if include_api:
@@ -282,7 +288,8 @@ def main(argv: list[str] | None = None) -> int:
     if include_docs:
         llms_txt = build_llms_txt(
             docs_base_url=DOCS_BASE_URL,
-            api_base_url=api_base_url,
+            stable_api_reference_url=stable_api_reference_url,
+            rolling_api_reference_url=rolling_api_reference_url,
             knowledge_base_url=f"{DOCS_BASE_URL}{KNOWLEDGE_DIR}/",
             version_label=args.version_label,
         )

diff --git a/tools/knowledge_indexing/api_index.py b/tools/knowledge_indexing/api_index.py
@@ -150,28 +150,34 @@ def _symbols(module: griffe.Module, package: str, base_url: str = "") -> tuple[S
         if not target.docstring:
             continue
 
+        canonical = target.canonical_path
         symbols.append(
             Symbol(
                 name=name,
                 kind=kind,
                 summary=_summary(target),
                 signature=_signature(target),
                 source=_source(target),
-                docs_url=_docs_url(module.path, f"{module.path}.{name}", base_url),
+                docs_url=_docs_url(canonical.rsplit(".", 1)[0], canonical, base_url),
             )
         )
 
         if kind == "class":
-            symbols.extend(_methods(target, module.path, name, base_url))
+            symbols.extend(_methods(target, name, base_url))
 
     return tuple(sorted(symbols, key=lambda symbol: symbol.name))
 
 
-def _methods(cls: griffe.Class, module_path: str, class_name: str, base_url: str = "") -> Iterator[Symbol]:
+def _methods(cls: griffe.Class, class_name: str, base_url: str = "") -> Iterator[Symbol]:
     """Documented public methods a class declares itself.
 
     `cls.members` excludes inherited members, which the base class documents.
+
+    `class_name` names each method as the caller reaches it, while the url comes
+    from the class's canonical path. The two differ for a re-exported class,
+    which mkdocstrings documents on its defining module's page.
     """
+    owner = cls.canonical_path.rsplit(".", 1)[0]
     for name, member in sorted(cls.members.items()):
         if name.startswith("_") or member.is_alias or not member.is_function:
             continue
@@ -185,7 +191,7 @@ def _methods(cls: griffe.Class, module_path: str, class_name: str, base_url: str
             summary=_summary(member),
             signature=_signature(member),
             source=_source(member),
-            docs_url=_docs_url(module_path, f"{module_path}.{qualified}", base_url),
+            docs_url=_docs_url(owner, f"{cls.canonical_path}.{name}", base_url),
         )
 
 

diff --git a/tools/knowledge_indexing/docs_index.py b/tools/knowledge_indexing/docs_index.py
@@ -227,9 +227,12 @@ def handle_endtag(self, tag: str) -> None:
         elif tag in _HEADING_TAGS and self._heading is not None:
             title = " ".join("".join(self._heading).split())
             anchor = self._sections[-1] if self._sections else ""
-            if title and anchor:
+            # Count every titled heading, even without a usable section id, so
+            # occurrence numbers stay aligned with `_read_structure`.
+            if title:
                 self._seen[title] += 1
-                self.anchors.setdefault((title, self._seen[title]), anchor)
+                if anchor:
+                    self.anchors.setdefault((title, self._seen[title]), anchor)
             self._heading = None
         elif tag == "a" and self._skip:
             self._skip -= 1