___ _ _ ____ / | __________(_|_) __ \____ _ ____ __ / /| | / ___/ ___/ / / / / / __ \| |/_/ / / / / ___ |(__ ) /__/ / / /_/ / /_/ /> </ /_/ / /_/ |_/____/\___/_/_/_____/\____/_/|_|\__, / /____/
You can contribute to AsciiDoxy by reporting issues, updating the documentation, fixing issues, or developing new features.
To report issues, or find issues to fix, go to the issue tracker on GitHub.
To make changes to the documentation or source code, fork the repository into your own GitHub account. Then create a Pull Request (PR) back to the AsciiDoxy main repository to contribute your changes.
Before making a PR make sure that:
New code is covered in unit tests.
All tests pass.
There are no linter warnings or errors.
MyPy analysis is successful.
There are two main branches to target for your PR:
masteronly for documentation changes that affect the currently released version.
developfor all other changes.
develop branch is merged periodically to
master to create a new release. The AsciiDoxy
website is generated from the
master branch manually.
AsciiDoxy is developed for python 3.7 and up. For development it is recommended to set up a virtual environment with all dependencies. Use the following commands to quickly set up the entire environment:
Then enable the virtual environment to be able to run tests:
The make file defines several other helpful commands:
Run unit tests using the current python version.
Generate HTML output for visual inspection.
Regenerate the Doxygen XML test data for all supported versions.
Check code style.
Static analysis using type hints.
Run all checks and tests on all available and supported python versions.
Create distribution packages in
Before creating a PR, you should run
make test-all to run all tests, the linter and the type
checker. Packaging and specified requirements are verified as well by installing into a clean
virtual environment. Tests will be run on all available, and supported, python versions.
Collect API reference information from local and remote files.
Reads the Doxygen XML files and creates an internal representation that can be converted to AsciiDoc.
Internal representation of API reference elements.
Enriches an AsciiDoc file with API reference information.
Templates used to generate API reference information.
The command line interface.
Adding programming language support
doxygenparser.driver) is the main entry point for loading the API reference from
Doxygen XML files. It uses an instance of
ParserBase to parse XML files with language specific
transformations. Too add support for an extra language:
Add a new module for the language in subpackage
Define a subclass of
LanguageTraitscontaining details on how to parse types for the language.
Add a subclass of
TypeParserusing the language traits implementation.
Add a subclass of
ParserBaseusing the type parser and language traits.
Register the parser in the constructor of
If needed, add aliases in
Add unit tests!
Adding methods for use in AsciiDoc files
The entry point for enriching an AsciiDoc file is
process_adoc(). It treats the AsciiDoc input
file as a Mako template. Any Mako syntax can
be used in the AsciiDoc file. API enrichment methods are provided by passing an instance of
the Mako processor. It is exposed in the document as
api. Add methods to
Api to provide more
functionality to document writers.
Supporting more kinds of API reference elements
API reference fragments are also generated from Mako templates. These templates are in
asciidoxy/templates and are organised in separate directories per programming language. To add
support for a specific API reference element, add a Mako template with the name of the element in
the directory for the corresponding programming language. It will automatically be picked up when an
insert method is called. The special method
getattr is used to provide the
Where possible, Doxygen XML files for testing are generated from custom source code. This allows
checking compatibility with different Doxygen versions. Inside the
tests directory there are
multiple directories for test data:
data: All test data. Handcrafted test data lives in the root of this directory.
data/adoc: AsciiDoc input files for testing. Usually pairs of
<NAME>.expected.adoc. The expected file contains what AsciiDoxy should output when processing the input file.
data/source_code: The source code from which Doxygen XML test data is generated.
data/generated/xml: Doxygen XML test data generated from the source code.
|A separate directory is created for each version of Doxygen. The tests will run on each directory.|
The expectations for the tests in
test_templates.py can be easily regenerated when templates have
been changed. Run
pytest --update-expected-results to overwrite the current expectations with the
new output. Make sure to check the diff to see if there are no unexpected side effects!
Releasing a new version
Only AsciiDoxy maintainers can release new versions of AsciiDoxy. To create a new release, follow these steps:
developupdate the version number in
Replace the unreleased heading in
CHANGELOG.adocwith the new version.
Create a PR from
master. Merge it when all checks are passed.
On GitHub go to
Draft a new release.
Set the version tag to the new version number (no prefix or suffix).
Set the description to
Copy the changelog into the description, and change the headers to MarkDown format.
Save the release. A GitHub action will be started to publish the release.
After the publishing GitHub action has completed, update the website (ask Rob).