python-doxygen
Reference documentation for python-doxygen
Loading...
Searching...
No Matches
ADR-006: Adopt sibling build, test, and documentation infrastructure

Date: 2026-09-11

Status

Accepted

Context

python-doxygen is implemented as a portable AWK filter and belongs to the same family of documentation filters as awk-doxygen and bash-doxygen. The initial milestone established the Python recognition contract, source-preserving Doxygen representation, behavior-focused fixtures, and source/dist artifact boundary, but its repository tooling remained intentionally smaller than the sibling projects.

The sibling repositories now provide a mature, already-used model for canonical Make targets, source/dist parity tests, pinned documentation dependencies, generated ADR navigation, reference documentation, and GitHub Pages publication. Keeping a different orchestration model in python-doxygen would create needless maintenance divergence without reflecting a Python-specific semantic requirement.

At the same time, mechanical copying would be incorrect. python-doxygen consumes Python while its own implementation source is AWK, so project reference documentation must use the AWK and Bash documentation filters rather than trying to use python-doxygen to document its own AWK implementation. Likewise, --compact exists to support the pseudo-language output models of the sibling filters and has no useful equivalent in the source-preserving Python representation.

Decision Drivers

  • Keep build, validation, and documentation workflows familiar across sibling Doxygen-filter repositories.
  • Preserve Make as the inspectable, local-first orchestration surface used by CI.
  • Keep documentation dependency acquisition explicit and reproducible.
  • Exercise both maintained source and generated consumer bytes.
  • Preserve the distinction between the implementation language, AWK, and the consumed source language, Python.
  • Avoid copying sibling behavior that has no Python-specific semantic purpose.

Decision

The repository SHALL adopt the applicable build, test, and documentation infrastructure used by awk-doxygen and bash-doxygen.

Canonical Make interface

The root Makefile SHALL remain the canonical interface for build, validation, documentation, and cleanup operations. It SHALL provide, as applicable:

make build
make test
make test-source
make test-dist
make test-doxygen
make checksums
make deps-docs
make deps-docs-check
make adr-index
make docs
make docs-canary
make docs-clean
make clean
make distclean

make test SHALL continue to run the same Python semantic regression suite against maintained doxygen-python.awk and generated dist/doxygen-python.awk. CI SHALL exercise the suite with at least mawk and GNU awk.

make test-doxygen SHALL exercise a focused Python integration fixture through Doxygen using the selected DOXYGEN_PYTHON_FILTER. The integration configuration SHALL remain separate from the root reference-documentation Doxyfile so project reference publication and Python-filter integration testing do not overload one configuration with two responsibilities.

Documentation dependencies

Documentation-only external artifacts SHALL be declared in dependencies-docs.txt and materialized beneath vendor/ through a directly bootstrapped, SHA-256-pinned bashdeps release. The dependency set SHALL include released awk-doxygen and bash-doxygen filters plus released adrctl tooling.

make deps-docs MAY use the network to synchronize those pinned bytes. make deps-docs-check, make adr-index, make docs, and make docs-canary SHALL consume prepared dependency state and SHALL NOT silently repair or update it.

Project reference documentation

The root Doxyfile SHALL generate disposable project reference documentation under doc/reference/. Maintained AWK source SHALL be filtered with the pinned AWK documentation filter, and maintained shell test harness source SHALL be filtered with the pinned Bash documentation filter. Markdown governance and project documentation SHALL be included directly.

The generated reference tree SHALL NOT be committed merely to support GitHub Pages. GitHub Pages publication SHALL regenerate the tree from source and publish the generated artifact.

The project SHALL generate an ephemeral doc/adr/README.md by combining maintained README.intro.md and README.outro.md framing with an ADR table of contents generated by pinned adrctl. The composite file is derivative state and SHALL remain ignored by Git.

Deliberate non-parity

The project SHALL NOT add a --compact mode merely to match sibling command-line interfaces. The Python representation preserves Python source and physical line correspondence rather than synthesizing a compact pseudo-language, so suppressing lines would work against the established representation contract.

AWK- and Bash-specific parser fixtures SHALL NOT be copied into the active Python regression path. Shared repository structure is desirable; false semantic symmetry is not.

Release publication and exact released-artifact validation are governed separately by ADR-007.

Alternatives Considered

Keeping the milestone-1 repository tooling minimal was rejected because the sibling projects already provide a proven maintenance model and the user has explicitly chosen repository parity as a project direction.

Copying the sibling repositories wholesale was rejected because their input languages and generated representations differ. In particular, using python-doxygen as the documentation filter for its own AWK implementation would confuse the consumer language with the implementation language, and copying --compact would add an interface without a coherent Python representation contract.

Running documentation dependency synchronization implicitly from make docs was rejected because acquisition and verification are different trust boundaries. Prepared, pinned state should be inspectable and verifiable independently of the documentation build.

Consequences

Contributors can use essentially the same Make workflow across the three sibling filter projects. CI and local development exercise the same build and test entry points, while reference documentation becomes reproducible from pinned released documentation tooling.

The repository gains generated vendor/, doc/reference/, and doc/adr/README.md state, all of which remain disposable and ignored. A fresh checkout that needs reference documentation must explicitly prepare documentation dependencies before running the non-repairing documentation targets.

Future sibling infrastructure may be adopted when it has an equivalent contract here, but project parity is not authority to bypass Python-specific ADRs or add interfaces without a semantic purpose.

Related Decisions

  • ADR-001 defines the Python recognition boundary.
  • ADR-002 defines the source-preserving Doxygen representation.
  • ADR-004 defines maintained and generated consumer artifact boundaries.
  • ADR-005 governs behavior-focused regression fixtures.
  • ADR-007 governs release publication and exact released-artifact canaries.