Repository navigation
PDF links: no dead links in a PDF (1/3) - #21
Open
tobiaskaestner wants to merge 3 commits into
Open
tobiaskaestner wants to merge 3 commits into
tobiaskaestner wants to merge 3 commits into
Conversation
In a PDF, the links of the needs to other documents use the base URL, but the Doxygen links did not: testmodule (Source, See also), symbol_needs (Declared in), testcoverage (the place of a body) and the tag-file routing got the relative HTML path in every build. A PDF has no sibling tree, so ../../dox-api/main_8c_source.html was dead in it. docrefs now gives these the URL by which this output links a peer (link_urls): the relative path in HTML, the base_url-rooted URL otherwise, as _peer_url already does for the needs. The extensions put the page's ../ prefix only in front of a relative URL (doxygen_parser.page_url). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
…se URL The pickled environment keeps each imported need with its URL. The digest of the imports covered the content of each needs.json, not the settings of the source. So after a new ZDOCS_DOC_BASE_URL, an incremental PDF build still linked the needs of other documents to the old base URL. A fresh doctree cache gave the right links. The digest now covers the settings of each source (base_url and the others) too. A change of them starts from a fresh environment, as a change of the content does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
volker-kempert
approved these changes
Oct 29, 2026
Two kinds of link from the HTML world are dead in a PDF: a link to a local server (a development base_url such as http://localhost:8000/) and a relative HTML path, which has no target next to the PDF. A PDF is mailed and filed, so such a link stays dead for good. The new pdf_links extension, loaded for every document, writes each of them as its text in a LaTeX build, and warns once per document with the count and the first URL. Set ZDOCS_DOC_BASE_URL to the published site to keep the links to other documents. Links inside the PDF and links to another host stay. It does not use the "internal" flag of a reference: sphinx-needs sets it on a needtable link to a need of another document too. Checked on the safety-toolbox PDFs: with the development base_url, 0 links to localhost and 0 relative links are left; with https://tiacsys.github.io/safety-toolbox/ all links to other documents and to Doxygen go to the site, with no warning. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
tobiaskaestner
force-pushed
the
tkaestner/pdf-links
branch
from
October 29, 2026 11:09
4d84b5c to
7e7ad96
Compare
volker-kempert
approved these changes
Oct 29, 2026
This branch has not been deployed
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 first of three stacked PRs for the PDF output: no dead links in a PDF. A PDF is mailed and filed, so a dead link in it stays dead.
Doxygen links use the base URL in a PDF. testmodule (Source, See also), symbol_needs (Declared in), testcoverage (the place of a body) and the tag-file routing got the relative HTML path in every build. In a PDF,
../../dox-api/main_8c_source.htmlhas no target. docrefs now gives the URL by which the output links a peer (link_urls): the relative path in HTML, the URL frombase_urlin the other builds. This is what_peer_urlalready does for the needs.A new base URL resets the imported needs. The digest in needs_config_state covered the content of each imported needs.json, but not the settings of the source. After a new
ZDOCS_DOC_BASE_URL, an incremental PDF build kept the old URLs. The digest now covers the source settings too.New extension pdf_links. In a LaTeX build, a link to a local server (for example a development
base_urlofhttp://localhost:8000/) or a relative HTML path becomes plain text. There is one warning per document, with the count and the first URL. Links inside the PDF and links to other hosts do not change. To keep the links to other documents, setZDOCS_DOC_BASE_URLto the published site.Checks: unit 515, zdocs docs 0 warnings. safety-toolbox PDFs: with the development base URL, 0 links to localhost and 0 relative links are left. With
https://tiacsys.github.io/safety-toolbox/, all links to other documents and to Doxygen go to the site, with no warning. The matching acceptance tests (zdocs-tests test_15) come in a separate zdocs-tests PR.🤖 Generated with Claude Code