|
python-doxygen
Reference documentation for python-doxygen
|
Accepted
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.
The repository SHALL adopt the applicable build, test, and documentation infrastructure used by awk-doxygen and bash-doxygen.
The root Makefile SHALL remain the canonical interface for build, validation, documentation, and cleanup operations. It SHALL provide, as applicable:
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-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.
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.
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.
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.
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.