Fix mkdocstrings cross-references not resolving to links in Zensical-built docs#4
Conversation
|
Would like to add details:
|
Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/ae1f437f-4e75-4afb-a797-a5d4be62346e Co-authored-by: OutSquareCapital <[email protected]>
…on, and docs updates Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/ae1f437f-4e75-4afb-a797-a5d4be62346e Co-authored-by: OutSquareCapital <[email protected]>
…ed ref handling, simplify rebuild script Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/ae1f437f-4e75-4afb-a797-a5d4be62346e Co-authored-by: OutSquareCapital <[email protected]>
Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/ae1f437f-4e75-4afb-a797-a5d4be62346e Co-authored-by: OutSquareCapital <[email protected]>
| - [Interoperability](interoperability.md): convert between types with various methods | ||
| - [Examples & Cookbook](examples.md): practical patterns and concrete examples | ||
|
|
||
| ## Cross-references |
There was a problem hiding this comment.
This whole section is irrelevant. Getting started is for end users, not for internal devs
There was a problem hiding this comment.
Removed in 2ec6231 — getting-started.md is back to its original state.
| @@ -0,0 +1,309 @@ | |||
| """Post-process the built site to resolve mkdocstrings cross-reference tags. | |||
|
|
|||
| Zensical does not call ``fix_refs`` from ``mkdocs-autorefs``, so the | |||
There was a problem hiding this comment.
This whole file need to follow pyochain patterns for iterations, just like the other scripts
There was a problem hiding this comment.
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()returnpc.Iter[...]_class_alias()and_try_import_module()returnpc.Option- All manual loops replaced with
pc.Iter(...).flat_map(...),.filter_map(...),.filter_star(...),.map_star(...),.for_each_star(...),.collect(),.sum(),.length()
There was a problem hiding this comment.
there's a shit ton of useless docstring documentation. clean that up. Those are internal scripts
There was a problem hiding this comment.
Done in 8fad116 — all docstrings trimmed to single-line summaries, matching the style of generate_docs.py and check_docstrings.py.
| @@ -83,3 +83,5 @@ | |||
| custom_fences = [ | |||
| { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }, | |||
There was a problem hiding this comment.
Why has this change been made?
There was a problem hiding this comment.
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.
|
@copilot act on my review comments |
…py with pyochain patterns Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/22463733-e40a-47a5-9090-ca23ca661686 Co-authored-by: OutSquareCapital <[email protected]>
…f syntax, improve lambda readability, rename counts variable Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/22463733-e40a-47a5-9090-ca23ca661686 Co-authored-by: OutSquareCapital <[email protected]>
| @@ -0,0 +1,309 @@ | |||
| """Post-process the built site to resolve mkdocstrings cross-reference tags. | |||
|
|
|||
| Zensical does not call ``fix_refs`` from ``mkdocs-autorefs``, so the | |||
There was a problem hiding this comment.
there's a shit ton of useless docstring documentation. clean that up. Those are internal scripts
|
@copilot how do you know that hyperlinks work now? Have you reproduced this locally? If yes, how? |
… like other internal scripts Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/283d78c5-7bab-414e-83dd-a71ffd826c23 Co-authored-by: OutSquareCapital <[email protected]>
Honestly, no — I haven't been able to reproduce it end-to-end. The sandboxed environment this agent runs in has Python 3.12, but pyochain requires Python 3.13+, so What the implementation is based on:
The script logic itself can be verified with a minimal synthetic HTML fixture (which I ran against the Python-3.12-compatible parts), but the full round-trip — |
Fantastic. Well done. For the warnings sections, why did you try to access those URL? What does this change concretely that you weren't able to access them? |
…amed closure _resolved Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/cb04ac0c-1861-42bd-a74f-5b952dfb126c Co-authored-by: OutSquareCapital <[email protected]>
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
Those warnings are generated automatically by the agent sandbox whenever a network request hits a domain that's on the firewall blocklist — they're not something I explicitly chose to navigate to. In this case it was likely the GitHub Pages domain (
Those |
…map, keep anchor as pc.Option Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/1f35ec7e-a523-4282-bf4b-e62da49dd622 Co-authored-by: OutSquareCapital <[email protected]>
| """Compute the relative URL from *from_page* to *to_url*.""" | ||
| split = pc.Iter(to_url.split("#", 1)) | ||
| to_url_no_anchor = split.first() | ||
| anchor: pc.Option[str] = split.next() |
There was a problem hiding this comment.
Since we use anchor only once, simply move this in the return line to chain with the map_or_else
There was a problem hiding this comment.
Done in d6a4e22 — anchor variable removed; split.next() is now inlined directly into the map_or_else on the return line.
Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/b5968a31-e75a-4bfb-9d2b-013b159e614e Co-authored-by: OutSquareCapital <[email protected]>
| @@ -0,0 +1,218 @@ | |||
| """Post-process the built site to resolve mkdocstrings cross-reference tags.""" | |||
There was a problem hiding this comment.
Style-wise this code is now good to go. I'm now wondering , would adding yarl as a dev dependency help here? Since we use quite a lot of URL, we could habdle those a concrete objects and potentially avoid various in-house str manipulations logic in this file.
As a a side note, please run uv run ruff check --fix --unsafe-fixes ; uv run ruff format if you haven't already
There was a problem hiding this comment.
Ruff run in 72bd093 — fixed 1 import ordering issue (moved pyochain import after the other third-party imports).
On yarl: it would clean up _relative_url a bit (no manual #-split, path parts via .parts), but the URLs here are root-relative paths (no scheme/host), so most of yarl's value comes from features we don't use. The remaining string logic is straightforward enough that the extra dependency doesn't pay for itself. Happy to add it if you feel otherwise.
Agent-Logs-Url: https://github.com/OutSquareCapital/pyochain/sessions/20c2f47a-de4e-4f51-afda-278dfeb4c797 Co-authored-by: OutSquareCapital <[email protected]>
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
Zensical never calls
fix_refs()frommkdocs-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):site/HTML to build an anchor-ID → absolute-URL map usingpc.Iter(...).sort().iter().flat_map(...)_reexport_alias_pairs()function returningpc.Iter[tuple[str, str]]; chained with file anchors and collected once into adict— no mutation<autoref>to<a class="autorefs autorefs-internal">with a correct relative URL computed usingVec.from_ref,iter().zip(),iter().slice(), andpc.Iter([".."]).cycle().take(); falls back to the parent class anchor for attribute refs; emits arichwarning for non-optional unresolved refsrich/rich.textfor all output, consistent with other scripts; CLI viatyper;SITE_DIRas a module-level constantzensical.toml— Registersmkdocs_autorefs._internal.references:AutorefsExtensionas a markdown extension, enabling[identifier][]/[label][identifier]cross-reference syntax in plain.mdpages, not just inside:::docstring blocks.github/workflows/docs.yml— Runsfix_autorefs.pybetweenzensical buildand the GitHub Pages deploy step.github/workflows/copilot-setup-steps.yml— New setup steps file that pre-installsuv, Python 3.13, and all project dependencies so the agent environment can run the full build and verify fixes end-to-endscripts/rebuild-docs.ps1— Updated to runfix_autorefs.pyafter the builddocs/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:
uv run zensical build— produces HTML pages containing<autoref>tagsuv run scripts/fix_autorefs.py— resolves 1166 cross-references, 0 unresolved<autoref>tags remainhref="../pyocollection#pyochain.traits._iterable.PyoCollection")