|
bash-doxygen
Reference documentation for bash-doxygen
|
Accepted
This ADR extends the documentation architecture established by ADR-005 and the stable/canary separation established by ADR-006. It makes the Architecture Decision Record corpus the landing page for generated Doxygen documentation by assembling a linked ADR table of contents into an ephemeral Markdown file before Doxygen runs.
The generated landing page is navigation, not architectural source. Maintained framing remains in separate Markdown fragments, ADRs remain authoritative for decision rationale, and doc/decisions.md remains the concise decision map.
All documentation-generation paths SHALL use the same landing-page assembly so stable Pages publication, current-source dogfood, and exact-release dogfood do not silently validate different documentation sites.
ADR-005 requires generated Doxygen reference documentation to be ephemeral, requires documentation-only dependencies to be isolated in dependencies-docs.txt, and deliberately keeps make docs offline after those dependencies have been prepared. It also explicitly permits maintained Markdown and ADR material to be part of the published Doxygen corpus.
ADR-006 adds two canary paths around that stable publication model. The current-source canary substitutes the repository's maintained doxygen-bash.awk, while the released-artifact canary substitutes the exact downloadable release artifact. Both are expected to reuse the stable Doxyfile and maintained documentation corpus as closely as possible.
The current Doxyfile includes the ADR directory, but its main page is the repository root README.md. The ADR corpus is therefore available as reference material without providing a useful architectural navigation surface at the site root. Related repositories now generate a linked ADR index from maintained introductory and closing fragments and use that generated composite as the Doxygen main page.
adrctl already owns the public generate toc report and is released as a single versioned Bash artifact with published SHA-256 verification data. Using a pinned released artifact lets this repository consume the same public interface a downstream project would use rather than implementing an independent ADR enumerator in Make or shell code.
The repository already has a role-specific documentation manifest and a strict network boundary. The new dependency and generation step must fit that model rather than weakening it for convenience.
make docs as an offline consumer of prepared documentation state.generate toc contract instead of maintaining a repository-specific ADR parser.The repository SHALL maintain these source files:
The documentation build SHALL generate:
by composing the maintained introduction, adrctl-generated linked ADR table of contents, and maintained outro.
doc/adr/README.md SHALL be generated state. It SHALL be ignored by Git and SHALL NOT become a second maintained list of ADRs.
The generated page SHALL be Doxygen's Markdown main page.
The documentation manifest SHALL include a released adrctl.bash artifact at:
The initial pin for this decision is:
The pin SHALL live in dependencies-docs.txt and SHALL be synchronized and verified through the same bashdeps boundary used for the released AWK and Bash Doxygen filters.
The Makefile SHALL NOT download adrctl independently, infer a moving latest release, or trust an unverified executable merely because it has the expected filename.
The released adrctl artifact is documentation tooling only. It SHALL NOT become an input to make build, the generated dist/doxygen-bash.awk artifact, the AWK runtime, or the filter regression semantics.
make deps-docs remains the operation that MAY access the network and repair missing or stale documentation dependencies.
make deps-docs-check remains a verification-only operation over already prepared dependency state.
A new target:
SHALL require the prepared vendor/adrctl.bash, maintained intro fragment, and maintained outro fragment. It SHALL NOT invoke make deps-docs, download anything, or repair dependency state.
make docs SHALL remain offline with respect to repository dependency acquisition. Its existing deps-docs-check prerequisite SHALL continue to verify all prepared documentation dependencies, including adrctl, before stable reference generation proceeds.
make adr-index SHALL write candidate output to a temporary file in the same directory as the final doc/adr/README.md and replace the final path only after adrctl completes successfully.
If generation fails, the temporary candidate SHALL be removed and an existing complete landing page SHALL not be intentionally replaced with partial output.
The target SHALL invoke the released artifact through Bash and the public report surface:
using the maintained intro and outro options supported by the pinned release. The Makefile SHALL not reproduce ADR discovery, logical numbering, title extraction, link construction, or sorting independently.
The common docs-canary target SHALL invoke make adr-index before invoking Doxygen.
This placement is intentional. Stable make docs already delegates final Doxygen generation to docs-canary with the pinned released AWK and Bash filters. The current-source and post-release workflows also call docs-canary with different Bash-filter paths.
Consequently, all three documentation roles SHALL consume the same generated ADR landing page:
A future documentation path that intentionally bypasses this common target must explicitly decide whether and why it should publish a different documentation corpus.
The Doxyfile SHALL set:
The generated page remains within the existing doc/adr input tree. The root README.md, doc/decisions.md, the Bash and AWK documentation standards, the ADR corpus, maintained filter source, and other already-selected material remain available as reference pages unless separately changed by governance.
README.intro.md and README.outro.md SHALL be excluded from standalone Doxygen publication because their content is already composed into the generated main page.
The ADR templates and generated reference output remain excluded under the existing publication model.
make docs-clean SHALL continue to remove the generated Doxygen tree under doc/reference/ as required by ADR-005.
make distclean SHALL additionally remove doc/adr/README.md along with other generated dependency/build state so a deep cleanup can return the repository to a fresh-checkout generated-state boundary.
Ordinary make docs-clean does not need to remove the generated Markdown intermediate merely to rebuild HTML. The next make adr-index invocation replaces the complete page atomically.
This decision introduces linked textual ADR navigation only.
Routine make adr-index, make docs, and make docs-canary SHALL NOT invoke adrctl generate graph or automatically compose DOT, Mermaid, SVG, PNG, or another ADR relationship graph into the landing page.
A repository may still use adrctl's graph report explicitly for another purpose. Such explicit use is separate from the stable documentation landing-page contract established here.
The adrctl executable is an externally produced documentation dependency and is therefore treated with the same supply-chain boundary as the existing released filters. Its identity is authorized by a reviewed immutable release URL and committed SHA-256 digest in dependencies-docs.txt.
make adr-index assumes that dependency preparation and verification have already established acceptable local bytes. Stable make docs enforces that assumption through deps-docs-check; canary workflows prepare and verify the same manifest before invoking the common documentation path.
Expected failure cases include:
vendor/adrctl.bash;deps-docs-check;A failure in one stage SHALL remain visible rather than being hidden by fallback to an older hand-maintained index or by silently downloading replacement bytes in make adr-index.
This preserves the current site root, but it leaves the ADR corpus as secondary navigation and does not address the goal of exposing the project's architectural history directly. The root README remains available as a generated reference page, so changing the main page does not remove it from the documentation corpus.
A committed generated index would be visible in ordinary repository browsing, but it would duplicate information derived from the ADR corpus and create mechanical synchronization diffs. ADR-005 already establishes generated reference documentation as ephemeral state, and the same principle applies to this generated navigation intermediate.
The repository could enumerate doc/adr/ADR-*.md, extract headings, sort names, and emit Markdown directly. That would create another ADR discovery and serialization implementation even though adrctl already owns and tests that public behavior. It was rejected in favor of consuming the released tool.
This would make an apparently generative target perform network access and repair, contradicting ADR-005's explicit acquisition-versus-consumption boundary. It was rejected so missing prepared state remains a clear actionable failure.
Pages-only assembly would leave local make docs and the two ADR-006 canaries validating a different site. It was rejected because shared documentation configuration is a core purpose of the common docs-canary target.
This would improve Pages while leaving current-source and exact-release canaries without the same main page. The canaries would then provide weaker evidence about the site they are intended to predict.
A graph can be useful for explicit analysis, but routine graph composition adds rendering and presentation concerns beyond the navigation goal. The current cross-repository convention intentionally keeps routine generated documentation graph-free.
The Pages root becomes an architecture-oriented entry point with mechanically current links to the managed ADR corpus.
Maintainers edit the intro, outro, ADRs, and decision summaries as source; they do not maintain the generated ADR list manually.
The documentation manifest gains one executable dependency, increasing the prepared documentation trust surface by one pinned artifact. This cost is accepted because the dependency supplies a public, reusable ADR discovery and TOC contract that would otherwise be duplicated locally.
Stable and canary documentation generation remain aligned. A change to the Doxyfile corpus or landing-page generation affects all three paths, while ADR-006 continues to vary only the Bash filter bytes under test.
A fresh checkout still requires make deps-docs before documentation generation. Once dependencies are prepared, stable and canary generation remain offline with respect to repository dependency acquisition.
The generated doc/adr/README.md may remain in a developer working tree between documentation builds, but it is ignored and replaceable. make distclean provides the complete generated-state cleanup boundary.