ITADN

Fix mkdocstrings cross-references not resolving to links in Zensical-built docs

#4Pull RequestCopilot 创建于 2026-04-09
C
Copilotcommented
Zensical never calls `fix_refs()` from `mkdocs-autorefs`, so every `<autoref>` tag emitted by mkdocstrings (type signatures, base classes, return types, user-written `[identifier][]` refs) was left as raw, unlinked HTML in the built site. ## Changes - **`scripts/fix_autorefs.py`** — New post-build script that resolves all `<autoref>` tags, written using pyochain iteration patterns (consistent with the other scripts in this folder): - Pass 1: scans all `site/` HTML to build an anchor-ID → absolute-URL map using `pc.Iter(...).sort().iter().flat_map(...)` - Extends the map with module-alias entries via a pure `_reexport_alias_pairs()` function returning `pc.Iter[tuple[str, str]]`; chained with file anchors and collected once into a `dict` — no mutation - Pass 2: rewrites every `<autoref>` to `<a class="autorefs autorefs-internal">` with a correct relative URL computed using `Vec.from_ref`, `iter().zip()`, `iter().slice()`, and `pc.Iter([".."]).cycle().take()`; falls back to the parent class anchor for attribute refs; emits a `rich` warning for non-optional unresolved refs - Uses `rich`/`rich.text` for all output, consistent with other scripts; CLI via `typer`; `SITE_DIR` as a module-level constant - **`zensical.toml`** — Registers `mkdocs_autorefs._internal.references:AutorefsExtension` as a markdown extension, enabling `[identifier][]` / `[label][identifier]` cross-reference syntax in plain `.md` pages, not just inside `:::` docstring blocks - **`.github/workflows/docs.yml`** — Runs `fix_autorefs.py` between `zensical build` and the GitHub Pages deploy step - **`.github/workflows/copilot-setup-steps.yml`** — New setup steps file that pre-installs `uv`, Python 3.13, and all project dependencies so the agent environment can run the full build and verify fixes end-to-end - **`scripts/rebuild-docs.ps1`** — Updated to run `fix_autorefs.py` after the build - **`docs/api-reference.md`** — Migrated all type links to cross-reference syntax (e.g. `` [`Iter[T]`][pyochain._iter.Iter] ``) ## Verified end-to-end The full round-trip was verified with Python 3.13 + uv in the agent sandbox: 1. `uv run zensical build` — produces HTML pages containing `<autoref>` tags 2. `uv run scripts/fix_autorefs.py` — resolves **1166 cross-references**, **0 unresolved `<autoref>` tags** remain 3. Sample resolved links confirmed with correct relative URLs (e.g. `href="../pyocollection#pyochain.traits._iterable.PyoCollection"`)
合并状态:未合并 9 条评论