Fix mkdocstrings cross-references not resolving to links in Zensical-built docs
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 条评论