docs: add derived-id section reference lint - #4340
Merged
Merged
Conversation
grandixximo
force-pushed
the
docs-anchor-lint
branch
2 times, most recently
from
August 5, 2026 04:06
e0f2541 to
b3b04bf
Compare
Contributor
Author
|
this looks like this now: 
Acceptable? or keep the warning only in the annotations, and remove the summary from here?? |
scripts/docs-anchor-check.py, wired into the htmldocs CI job with --enforce, flags <<_derived>> xrefs and link:...html#_derived URLs whose target has no explicit [[anchor]] in docs/src. Derived ids come from section titles, so such references break when a title is translated or retitled. Pin the target with an explicit anchor instead. The lint reads only the English sources, so translations cannot trip it. Also pins the remaining lint hits, all same-page links in untranslated man pages (_subcommands, _mbccs_file_format, _modbus_functions, _modbus_types, _hal_types). Explicit ids match the auto-generated ones, so output is unchanged. With the five anchors from LinuxCNC#4339 merged, the lint reports the tree clean.
grandixximo
force-pushed
the
docs-anchor-lint
branch
from
August 5, 2026 10:54
b3b04bf to
28b8909
Compare
Contributor
Author
|
Tested as working without BTW I also cleaned up the rest of the html broken links warnings coming from the translations in weblate, not sure when those will gurgle up, after that we shall have a squeaky clean tree (insert here humorous comment). |
Contributor
So clean the birds will refuse to sit on the branches of the tree and silence was heard. |
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
2 participants
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.
Companion to #4339 (independent, either merge order).
Sections linked via auto-generated AsciiDoc ids (
<<_normal_download>>xrefs,link:...html#_ini_settings[...]URLs) break in translated docs when the section title is translated, because asciidoctor derives the id from the title text. #4339 pins the five targets that are broken in translations today. This PR makes sure the pattern does not regrow.scripts/docs-anchor-check.pydoes two passes over docs/src: collect every explicit anchor definition ([[id]],[#id],id=,anchor:id[]), then report each<<_derived>>xref or#_derivedlink URL whose target is not explicitly defined. Namespaced anchors all carry a colon by convention, so a_-prefixed target with no colon is a derived id.It is wired warn-only into the htmldocs CI job (same pattern as
htmlcheck.sh -w), printing offenders with file:line and writing the list to the GHA job summary. Flip to--enforceonce the tree is clean and the check has had a burn-in.Also included: explicit anchors for the remaining lint hits, all same-page links in untranslated man pages (
_subcommandsin linuxcncrsh.1,_mbccs_file_format,_modbus_functions,_modbus_types,_hal_typesin mesambccc.1). The explicit ids match the previously auto-generated ones, so rendered output is unchanged; I verified the ids in the built HTML.Current lint output on this branch is exactly the five references pinned by #4339, so the check turns clean as soon as that PR lands.