Documentation tools and preparation¶
Use this reference to prepare one maintained documentation environment. The qualified build tuple is Linux x86_64 with CPython 3.12. The local preparation uses CPython 3.12.14; CI selects the same patch version. Documentation tool qualification does not grant firmware, hardware or product qualification.
Prepare a fresh prefix¶
Run from the repository root, with CPython 3.12 available:
python3.12 tools/documentation/install.py \
--prefix build/docs-tools --cache build/docs-tool-cache
Preparation may download archives over HTTPS. It verifies the entire archive
closure before creating the prefix. Wheel installation then uses --no-index,
--find-links and --require-hashes; no transitive package is left for a fresh
online resolution. Native packages are extracted locally without sudo or
system package installation.
For an independent installation from a previously prepared cache:
python3.12 tools/documentation/install.py \
--prefix build/docs-tools-restored --cache build/docs-tool-cache --offline
The expected result is exit code zero and installation.json in the fresh
prefix. It records the lock digest, observed tool versions, kernel, resolved ELF
closure, archive digests, installed file digests and copied license digests.
The installed bin/fc-match must resolve Noto Sans CJK SC from the locked font
package. A missing archive, changed byte, failed command or mismatched font fails
preparation and leaves no success prefix.
An existing prefix is rejected. Choose a fresh path for an upgrade; do not silently mutate an installation already referenced by build evidence. Archive cache corruption also fails rather than being silently replaced by a download.
Use the single documentation CLI¶
Run the maintained CLI with the prepared Python and explicit tool prefix:
build/docs-tools/venv/bin/python tools/dev/dev.py docs doctor \
--tool-prefix build/docs-tools
build/docs-tools/venv/bin/python tools/dev/dev.py docs check \
--report build/docs-check.json
build/docs-tools/venv/bin/python tools/dev/dev.py docs build \
--tool-prefix build/docs-tools --language all --output build/documentation
build/docs-tools/venv/bin/python tools/dev/dev.py docs package \
--build build/documentation --output ../nexus-documentation-packages
install.environment(prefix) returns a verified subprocess environment with the
locked tool executables first on PATH. install.diagnose(prefix) rejects a
changed lock, changed installed file or changed license before reporting tool
identity. Neither operation installs or downloads tools. Builds must generate
fresh XML and HTML; a former successful output cannot rescue a failed command.
The scripts/tools/docs.py, .sh, .ps1 and .bat entries only forward to this
CLI. Legacy all, doxygen and sphinx targets all select the same complete
strict build. Removed generation modifiers are rejected; wrappers cannot create
a fallback Doxyfile or Sphinx configuration. Windows and macOS wrappers preserve
CLI forwarding, while a formal build still requires the maintained Linux tuple.
CI permission boundary¶
docs-build.yml has only contents: read. It prepares tools explicitly, runs
source checks, builds both languages, packages offline output and records observed
job identity. A failed build has no successful documentation upload.
The package producer writes outside the source checkout. CI then copies the
verified result to fresh ignored upload staging, compares the archive digest and
verifies the copied manifest and payload before the existing job-identity gate.
The staging copy does not rebuild or replace the original package.
docs-publish.yml runs only for the reviewed docs-delivery branch. Its read-only
job verifies the prepared public bytes and publication receipt before uploading a
Pages artifact. The separate deployment job alone has Pages and OIDC write
permissions and uses the nexus-documentation environment. It never checks out
or executes external pull-request source code. Deployment branch rules and
actual remote execution remain independently observable repository state.
License and upgrade handling¶
Each native archive carries its Debian copyright files. The locked base-files
archive supplies every referenced complete text in licenses/common-licenses/;
preparation rejects a missing shared license reference. Wheel license files are
copied from the verified wheel; the five upstream wheels which omit license text
use checked-in texts extracted from their exact verified source distributions.
The lock records source archive digest, member and extracted text digest. The
Doxygen archive carries its complete license text. Preparation copies these
texts into prefix/licenses/; packaging retains the applicable license payload.
To upgrade, review upstream changes and licenses, resolve one new exact closure, update both lock and hash requirements, execute a fresh online preparation and an independent offline preparation, then run strict bilingual build, diagram freshness, package verification and restoration. Retain raw failures and results; an updated version string alone is insufficient acceptance evidence.