Repository navigation
Make the source links really resolve to source files instead of the rendered Doxygen HTML - #14
Merged
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Missing build dependencies and incomplete input tracking can produce absent or stale source links.
4 open findings
What changed in this PR
Adds source-listing links for test cases, procedures, symbols, and coverage bodies.
Changes:
- Resolves Doxygen source pages and line anchors from generated XML.
- Integrates source links into Sphinx extensions and styling.
- Adds documentation, fixtures, and tests.
| File | Description |
|---|---|
sphinx/zdocs_conf.py |
Exposes Doxygen document metadata. |
sphinx/_static/zdocs-needs.css |
Styles coverage source locations. |
sphinx/_scripts/rst_builders.py |
Emits source-listing links. |
sphinx/_scripts/doxygen_parser.py |
Resolves Doxygen source pages. |
sphinx/_scripts/_tests/test_rst_builders.py |
Tests source-link RST. |
sphinx/_scripts/_tests/test_doxygen_parser.py |
Tests source-page resolution. |
sphinx/_fixtures/doxygen/test__queue_8c.xml |
Adds queue source fixture. |
sphinx/_fixtures/doxygen/test__helpers_8c.xml |
Adds helper source fixture. |
sphinx/_fixtures/doxygen/index.xml |
Indexes fixture source files. |
sphinx/_fixtures/doxygen/Doxyfile.xml |
Enables fixture source browsing. |
sphinx/_fixtures/doxygen-symbols/Doxyfile.xml |
Configures header listings. |
sphinx/_extensions/test_module.py |
Links tests and procedures to source. |
sphinx/_extensions/test_coverage.py |
Links coverage bodies to source. |
sphinx/_extensions/symbol_needs.py |
Links symbol declarations to source. |
sphinx/_extensions/_tests/test_test_module.py |
Tests test-module links. |
sphinx/_extensions/_tests/test_symbol_needs.py |
Tests symbol source links. |
sphinx/_extensions/_tests/test_adequacy.py |
Tests coverage source links. |
scripts/docrefs.py |
Registers Doxygen XML/HTML locations. |
doc/manual/reference/directives-and-roles.rst |
Documents source-link behavior. |
doc/manual/howto/render-test-specifications.rst |
Documents source-browser setup. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+699
to
+700
| try: | ||
| root = ET.parse(self.xml_dir / "index.xml").getroot() |
Contributor
Author
There was a problem hiding this comment.
Fixed. SourcePages.inputs holds every XML file that it read: Doxyfile.xml, index.xml and each file compound of a lookup. testmodule, symbolneeds and testcoverage record them as inputs of the document after the lookups.
Doxygen writes a source listing of a file (<refid>_source.html, with a line anchor l%05d) for every code file with SOURCE_BROWSER = YES, and for the headers with VERBATIM_HEADERS = YES. SourcePages reads the two options from the Doxyfile.xml beside the XML and finds the listing of a file by its path. The Source line of a test case or a procedure now links to its line in the listing; without listings it links to the group page, as before. The "Declared in" line of a symbol need links to the declaration's line in the listing, if there is one. SourcePages.inputs holds every XML file that it read (Doxyfile.xml, index.xml and each file compound of a lookup). testmodule and symbolneeds note them as inputs of the document, so a new Doxygen run reads the document again. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
The place of a body in the adequacy table (kernel/thread.c:344-358) now links to the first line of the body in a Doxygen source listing. The registry key testmodule.coverage_source_docs names the Doxygen documents to look in, in order. zdocs_conf gives it to the build as testcoverage_source_docs, and each builder of the document waits for these Doxygen documents (the same stage-2 edge as for doxygen_source). The registry gives each kind: doxygen document's XML directory and URL to zdocs_conf as zdocs_doxygen_docs. The XML files that the lookups read are inputs of the document. The body path is relative to testmodule_root, so a listing matches if one path ends with the other and only one file of the document matches. The form and place of a body is now a paragraph of class zd-adq-loc, not a role, because a role cannot hold a link. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
tobiaskaestner
force-pushed
the
tkaestner/source-listings
branch
from
October 13, 2026 19:06
99ec3f6 to
e2de78e
Compare
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.
The Source link of a test case or procedure, the "Declared in" link of a symbol need and the place of a body in the adequacy table now go to the line in Doxygen's source listing (
<file>_source.html#lNNNNN). Before, they went to the rendered member documentation.doxygen_parser.SourcePagesreadsSOURCE_BROWSERandVERBATIM_HEADERSfromDoxyfile.xmland finds the listing of a file by the file compound inindex.xml. It does not rebuild Doxygen's escaping of file names. Without a listing, the link stays as it was before.testmodule.coverage_source_docsnames the Doxygen documents to look in, in order. Each builder of the document waits for them. They need the top-leveldoxygen_xml: true.🤖 Generated with Claude Code