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

[Copilot]

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(...).flat_map(...).for_each_star(...)
  • Extends the map with module-alias entries discovered via Python introspection (e.g. pyochain.traits.PyoIterator → canonical pyochain.traits._iterable.PyoIterator), using filter_map, flat_map, filter_star, and for_each_star
  • Pass 2: rewrites every <autoref> to <a class="autorefs autorefs-internal"> with a correct relative URL; falls back to the parent class anchor for attribute refs (Err.error → Err); emits a rich warning (with page URL) for non-optional unresolved refs
  • Uses rich/rich.text for all output, consistent with other scripts

• 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

• 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])

Usage example

<!-- in any .md page -->
[`Iter[T]`][pyochain._iter.Iter] lazily wraps any iterable.
[pyochain.rs.Option][] is returned by methods that may produce no value.

Both forms now resolve to clickable links after zensical build && uv run scripts/fix_autorefs.py.

[OutSquareCapital]

Would like to add details:

• it concerns the documentation website
• we use zensical to build it, relevant info is in the pyproject for the config
• there's a bash script in the scripts folder and a github workflow related to building it

[OutSquareCapital]

This whole section is irrelevant. Getting started is for end users, not for internal devs

[Copilot]

Removed in 2ec6231 — getting-started.md is back to its original state.

[OutSquareCapital]

This whole file need to follow pyochain patterns for iterations, just like the other scripts

[Copilot]

Rewritten in 2ec6231 using the same patterns as the other scripts (generate_docs.py, check_docstrings.py). Key changes:

• import pyochain as pc + import rich/rich.text
• _file_anchors() and _module_aliases() return pc.Iter[...]
• _class_alias() and _try_import_module() return pc.Option
• All manual loops replaced with pc.Iter(...).flat_map(...), .filter_map(...), .filter_star(...), .map_star(...), .for_each_star(...), .collect(), .sum(), .length()

[OutSquareCapital]

Why has this change been made?

[Copilot]

The AutorefsExtension enables [text][identifier] and [identifier][] cross-reference syntax in regular markdown pages (like api-reference.md). Without it, [``Iter[T]``][pyochain._iter.Iter] in a .md file would be treated as a broken markdown reference link and rendered as plain text. With the extension, zensical's markdown processing converts these into <autoref> tags, which fix_autorefs.py then resolves to proper <a> links.

If you'd prefer not to use this syntax in the markdown docs, the extension can be removed and api-reference.md can be reverted to plain links — let me know.

[OutSquareCapital]

@copilot act on my review comments