zdocs Manual
v0.0-dev+g7f1b9d5

Tutorials

  • Tutorials

How-to guides

  • How-to guides

Reference

  • Reference

Explanation

  • Explanation
    • Architecture
    • The registry, and what it derives
    • The deploy tree
    • Documents zdocs does not build
    • From annotated C to a test report
    • Engineering guidelines
    • Documentation guidelines
    • Decisions
      • 0001. zdocs is a Zephyr module, included by name
      • 0002. Acceptance tests live in a consumer repository, over one cumulative fixture
      • 0003. The engine carries its own unit suite, in the engine repository
      • 0004. The registry is the single source of truth for document declarations
      • 0005. Remote documents are three kinds, not one
      • 0006. The deploy tree is organised by builder, not by document
      • 0007. Doxygen XML is engine-managed, and lives outside the servable tree
      • 0008. The Doxygen tag file is named doxygen.tag
      • 0009. Need types and links are a consumer-supplied role→name mapping
      • 0010. The engine payload is split by tool, freeing doc/ for documentation
      • 0011. Documentation structure: Diátaxis, arc42-lite, and two documents
      • 0012. Cross-document links in the HTML tree are relative

Manual

  • zdocs Manual

Reference

  • zdocs API Reference
zdocs Manual
  • Explanation
  • Decisions
  • 0012. Cross-document links in the HTML tree are relative
  • View page source

0012. Cross-document links in the HTML tree are relative

Status

Accepted, 2026-09-29. Supersedes the “absolute URLs under the base URL” consequence of 0011. Documentation structure: Diátaxis, arc42-lite, and two documents.

Context

Every cross-document Sphinx link — the sidebar navigation, intersphinx references, doxylink roles and imported needs — was an absolute URL under the registry’s base_url. A deploy tree therefore only worked when served at exactly that URL: a local preview was pinned to one host and port, a branch deploy needed a rebuild with an override, and a tree opened from file:// had dead Sphinx links. Doxygen’s links were relative all along.

Decision

Output built into deploy/html/ links its locally built peers by path relative to its own HTML root. Each consumer of that path resolves it for the referencing page: intersphinx and sphinx-needs against the document’s depth, doxylink against the source file’s, the sidebar template via content_root. base_url still applies to every other output — a PDF, the html-live preview — which has no sibling tree to be relative to. Remote documents keep their absolute remote-url.

Consequences

  • deploy/html/ can be served from any host, port or subdirectory, or browsed from the filesystem, without a rebuild.

  • A PDF still bakes base_url in, so a registry’s base_url should name the published site rather than a local preview.

  • needflow graphs render an imported need with a relative URL as an unlinked node: sphinx-needs only links external needs whose URL has a scheme.

Previous

© Copyright 2026, zdocs Manual.