|
bash-doxygen
Reference documentation for bash-doxygen
|
Accepted
bash-doxygen exists to translate intentionally documented Bash source into a Doxygen-friendly representation. The repository should therefore generate and publish its own reference documentation through the same consumer-facing filter path used by downstream projects.
The repository contains maintained AWK in doxygen-bash.awk and maintained shell code in tests/run-tests.sh. The AWK implementation can be documented by a released awk-doxygen artifact, while the shell source can be documented by a released bash-doxygen artifact. Using both filters in one reference build provides a practical mixed-language integration example without coupling their implementations or release cadences.
Generated Doxygen HTML is derived output. Committing the generated tree would create large mechanical diffs and duplicate information already maintained in source comments, Markdown documentation, and ADRs.
Documentation filters are executable development dependencies. Their exact bytes therefore need the same explicit, reviewable dependency boundary used by other supply-chain-sensitive tooling. bashdeps already provides immutable URL, destination, and SHA-256 pinning and supports role-specific manifests.
awk-doxygen and bash-doxygen independently versioned.Reference documentation SHALL be generated under:
doc/reference/ SHALL be generated state, SHALL be ignored by Git, and SHALL be removable through make docs-clean.
Documentation-only external dependencies SHALL be declared in:
The repository SHALL bootstrap one pinned released bashdeps.bash artifact directly, verify its committed SHA-256 digest before execution, and use that bootstrap to synchronize dependencies-docs.txt beneath vendor/.
The documentation manifest SHALL pin released filter artifacts by immutable release URL and committed SHA-256 digest. At the time this decision is adopted, the stable publication pins are:
The AWK filter used by Doxygen SHALL therefore be the vendored, bashdeps-verified release artifact. The Bash filter SHALL likewise be the vendored, bashdeps-verified release artifact. Stable publication SHALL NOT use the repository-local maintained Bash filter merely because it is available.
make deps-docs MAY access the network because it synchronizes missing or stale documentation dependencies. make deps-docs-check SHALL verify prepared bootstrap and manifest state without network access or repair.
make docs SHALL be offline with respect to repository dependency acquisition. It SHALL require prepared documentation dependencies, verify them through make deps-docs-check, remove prior generated reference output, validate the pinned filters against representative maintained source, and invoke Doxygen. It SHALL NOT invoke make deps-docs or otherwise repair missing dependency state.
The Doxygen configuration SHALL:
vendor/doxygen-awk.awk for maintained .awk input;vendor/doxygen-bash.awk for maintained .sh and .bash input;EXTRACT_STATIC = YES so file-local synthetic AWK rule entities are visible; andvendor/, generated distribution output, generated reference output, and regression fixture trees from published source material.GitHub Pages publication SHALL regenerate doc/reference/ from the checked-out revision rather than publishing committed generated HTML. The Pages workflow SHALL explicitly synchronize and verify documentation dependencies before running make docs, then upload doc/reference/ as the Pages artifact.
This would exercise current source, but it would not prove the released consumer artifact and dependency-acquisition path used by downstream projects. Current source is valuable as a canary and is governed separately by ADR-006; stable Pages publication uses pinned released bytes.
This duplicates acquisition and checksum logic and creates a CI-only dependency path. It was rejected in favor of the same bashdeps manifest used locally.
This hides network and repair behavior inside a generation target. It was rejected so dependency preparation remains explicit and make docs can be used as an offline validation step after state is prepared.
This was rejected because the HTML is reproducible derived output and would add large mechanical diffs without becoming the source of truth.
This was rejected because AWK and Bash have distinct source semantics and independently governed filters. A shared Pages site does not justify coupling their implementations.
A fresh checkout must run make deps-docs before local reference generation. Once dependencies are prepared, make docs and make deps-docs-check operate without repository dependency acquisition.
The published site demonstrates the released awk-doxygen and bash-doxygen consumer artifacts against real maintained source. A stable pin means Pages does not change merely because a newer filter release appears; proactive detection of new-source and new-release breakage is provided separately by ADR-006.
Generated reference output remains disposable and can always be rebuilt from the maintained revision plus pinned dependency declarations.
doxygen-bash.awk consumer artifact.