Repository navigation
NatSpec: repository-relative Git Source links via fix-links.py - #328
Merged
Merged
Conversation
Slice 4 of the documentation refresh plan. The 30 committed NatSpec pages linked their sources to blob/<commit>/src/... on GitHub: the path lacked the contracts/ prefix and the commit is on no branch, so every link was a 404, and the link checker skips http links. fix-links.py now rewrites each Git Source link into a link relative to the page, pointing at contracts/src/, and rewrites the homepage's relative links (a copy of contracts/README.md) only when they do not already resolve, so a second run changes nothing. It is applied to the committed pages: one line per page. Foundry 1.8.6 no longer emits mdBook Markdown; forge doc now writes a Vocs site scaffold. The committed mdBook pages stay the maintained reference, so the natspec README, contracts/README.md, and its homepage copy no longer tell readers to run forge doc. progress.md marks Phase 3 merged as #327 and records the Foundry change.
3 tasks done
Greaker
added a commit
that referenced
this pull request
Oct 27, 2026
Slice 5 of the documentation refresh plan. THIRD_PARTY_LICENSES.md: snapshot dated October 27, 2026; a new nginxinc/nginx-unprivileged row (BSD-2-Clause, NB UI runtime stage); the Node.js row covers the NB UI build stage; the Blockscout application row says it is built locally from pinned source tags, since upstream no longer publishes release images. Every image pinned in common/ now maps to a row. CONTRIBUTING.md: the NB Bond API block uses the root-workspace npm ci that CI uses, a new NB UI block mirrors its workflow, the Contracts block adds check-verify-latest-mapping.sh, and a Repository Checks block lists the verification scripts CI runs and when each applies. README.md lists services/nb-ui/AGENTS.md, and the ADR 0001 index entry says it is superseded by ADR 0003. progress.md marks Phase 4 merged as #328.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/plans/documentation-refresh/. The 30 committed NatSpec pages linked their sources toblob/<commit>/src/…on GitHub; the path lacked thecontracts/prefix and the commit is on no branch, so every link was a 404 (the link checker skipshttplinks).contracts/docs/natspec/fix-links.pynow rewrites eachGit Sourcelink into a page-relative link tocontracts/src/, and rewrites the homepage's relative links only when they do not already resolve, so a second run changes nothing. Applied to the committed pages: one line per page.forge docnow writes a Vocs site scaffold. The committed mdBook pages stay the maintained reference: the natspec README,contracts/README.md, and its homepage copy no longer tell readers to runforge doc.progress.mdmarks Phase 3 merged as Docs: drop removed behaviour; refresh diagrams and known issues #327 and records the Foundry change as a deviation.Documentation and one standard-library Python script; no Solidity changes.
Test plan
python3 scripts/verification/check-markdown-links.py(now validates the 30 source links)python3 scripts/verification/check-public-repo-hygiene.pygrep -r "blob/" contracts/docs/natspec/src/srcreturns nothingpython3 contracts/docs/natspec/fix-links.pyrun reports 0 changed filescontracts/README.mdcopy reproduces the hand-fixed links