    ___              _ _ ____
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/

Contributing

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:

master only for documentation changes that affect the currently released version.
develop for all other changes.

The develop branch is merged periodically to master to create a new release. The AsciiDoxy website is generated from the master branch manually.

Development environment

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:

make virtualenv

Then enable the virtual environment to be able to run tests:

. .venv/bin/activate

The make file defines several other helpful commands:

make unit-test: Run unit tests using the current python version.
make visual-test: Generate HTML output for visual inspection.
make generate-test-xml: Regenerate the Doxygen XML test data for all supported versions.
make lint: Check code style.
make type-check: Static analysis using type hints.
make test-all: Run all checks and tests on all available and supported python versions.
make dist: Create distribution packages in dist/.

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.

Architecture overview

Components:

collect: Collect API reference information from local and remote files.
doxygenparser: Reads the Doxygen XML files and creates an internal representation that can be converted to AsciiDoc.
model: Internal representation of API reference elements.
generator: Enriches an AsciiDoc file with API reference information.
templates: Templates used to generate API reference information.
cli: The command line interface.

Adding programming language support

Driver (in 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 doxygenparser.
Define a subclass of LanguageTraits containing details on how to parse types for the language.
Add a subclass of TypeParser using the language traits implementation.
Add a subclass of ParserBase using the type parser and language traits.
Register the parser in the constructor of Driver.
If needed, add aliases in safe_language_tag.
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 Api to 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 insert_<kind> and link_<kind> methods.

Coding style

For coding style we use PEP8, enforced by yapf. For docstrings we follow Google Style.

Test data

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>.input.adoc and <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:

On develop update the version number in asciidoxy/_version.py.
Replace the unreleased heading in CHANGELOG.adoc with the new version.
Create a PR from develop to master. Merge it when all checks are passed.
On GitHub go to Releases and click Draft a new release.
Set the version tag to the new version number (no prefix or suffix).
Set the description to AsciiDoxy <VERSION>.
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).