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

What is AsciiDoxy?

In essence AsciiDoxy is a preprocessor for AsciiDoc files. It looks for specific tags in these files and replaces them with valid AsciiDoc syntax. The information it inserts into the AsciiDoc files comes from Doxygen XML output.

1. Collects Doxygen XML and include files

Doxygen XML files are collected from remote HTTP servers, from the local file system, or a combination of both. What files are collected is specified in a package specification file and optionally a version file. See Package specification for details.

The packages can also contain other files that can be included in the documentation. These can be other AsciiDoc files, images, and other included files. The included AsciiDoc files can also contain AsciiDoxy directives.

2. Copies files to an intermediate directory

The input file and all files from the same directory and subdirectories will be copied to an intermediate directory. After this all adoc directories from the downloaded archives will also be copied inside the intermediate directory preserving their directory structure.

3. Parses Doxygen XML

The downloaded Doxygen XML files are parsed into an internal representation that can be converted to AsciiDoc on demand. References between separate packages are detected and resolved.

The parsing takes the source language into account. Specific cases for each language, like the format of type specifications, are handled based on the language specified in the Doxygen XML files.

4. Preprocesses Asciidoc files

The input AsciiDoc file is preprocessed using Mako. Mako looks for special syntax, the most common being ${…}. Any valid python code can be placed between the braces, and will be executed by Mako. For more details on the syntax, see the Mako syntax documentation.

The code executed by Mako inserts additional AsciiDoc into the file. Methods are provided to use the information from the Doxygen XML files. See the reference documentation for more details.

Consistency checking is performed to make sure links to, and between, API reference documentation are valid. Depending on the command line options either a warning or an error is thrown if an inconsistency is found.

The results of preprocessing are pure AsciiDoc files. They are stored as temporary files next to the input files inside the intermediate directory. This should preserve all relative links to other files.

5. Invokes Asciidoctor

When preprocessing is successful, Asciidoctor is invoked to generate single- or multi-paged HTML output depending on whether the --multi-page option was set.