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


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.8.7 (10 Sep 2023)


  • Python path management to easily include external python scripts. By default the directory containing the document being generated is added to the python path when the file is generated. The python path can be overridden on the command line. For packages python scripts can be included in a separate directory and specified in the contents file.


  • #73: Do not crash on Doxygen files with invalid encoding or XML and report a clearer error.

  • #73: Do not try to link to elements for which Doxygen has generated a refid, but where the element itself is missing.

0.8.6 (4 Sep 2022)


  • User name and password for HTTP package sources can be specified in the package spec file. The user name and password can be either hardcoded in the spec file or can be provided in an environment variable. If no user name or password is specified, the local netrc file is used. Thanks to Andrey Potapov for providing the netrc implementation.

0.8.5 (25 Feb 2022)


  • Escape links in descriptions containing double underscores to prevent triggering a known AsciiDoctor bug.

  • In descriptions text after an unsupported or unknown XML tag was missing.

  • Exceptions raised from AsciiDoc files were not handled correctly and raised another exception instead of showing a human friendly trace back.

0.8.4 (12 Jan 2022)


  • The wheel distribution was missing required CSS files.

0.8.3 (12 Jan 2022)


  • C++: Support template parameter descriptions for functions/methods and classes.


  • AsciiDoxy now uses its own stylesheets for added functionality like multipage TOC and multipage navigation. These stylesheets are extensions of the default AsciiDoctor stylesheet. They can still be overridden from the command line.

  • The multipage navigation bar now floats at the bottom of the screen filling the full width of the document body.

  • Including a document multiple times or both including and embedding the same document is now a warning or error.


  • Spaces in insert and link commands are ignored.

  • Array types (like Type[]) are properly supported for C++, Java and Objective C.

  • Use CSS directly to update margins to accommodate the multipage toc. No more JavaScript causing jumping pages.

0.8.2 (30 Dec 2021)


  • The required version for importlib_resources was too strict, causing installation issues.

0.8.1 (29 Dec 2021)


  • Running AsciiDoctor automatically is now optional. By using --backend adoc the generated AsciiDoc files are exported to the output directory, instead of the output of AsciiDoctor. This allows direct use of the AsciiDoc by other tools. The generated AsciiDoc is now optimized for this use case by not having any absolute paths, temporary files, and fragment files.

  • Experimental. Replace the builtin templates for generating API reference with your own customized versions. Provide a directory that overrides the builtin templates and allow specifying a different template to use in the insert command.

  • For increased performence in subsequent runs, generated python code for templates and input documents is cached in the build directory. Use command line argument --cache-dir to set a different location for the cache.

  • Command-line arguments are exposed inside AsciiDoc files through the config object .


  • Embedded files, inserted with include and always_embed=True, are no longer using temporary files.

  • Linking to an embedded file from outside the file where it is embedded is now possible iff the file is embedded only once. If the file is embedded multiple times it can only be linked from those files that embed it.

  • Minimum supported python version is now 3.7. Python 3.6 is end of life.

  • The Ruby interpreter is now started only once to process all generated AsciiDoc files. This significantly decreases the time required to process a large number of pages in multipage mode.

  • Unknown arguments are no longer passed through to AsciiDoctor. Commonly used arguments are explicitly supported by AsciiDoxy now. If you need to pass additional arguments, use the adoc backend to generate the AsciiDoc files and manually run AsciiDoctor on the output.


  • Removed unneccessary pass for partial matches when resolving references. Resolving references is now almost instantaneous (on large code bases). The old pass was mostly finding incorrect matches.

0.8.0 (29 Oct 2021)


  • Completely rewritten description parser for Doxygen. It supports more kinds of tags and inserts much less whitespace in the resulting AsciiDoc. It more closely follows the way Doxygen intends to format the descriptions.

    • Support dot and plantuml diagrams in Doxygen descriptions. They require AsciiDoctor-Diagram to be rendered. In the Doxyfile the option PLANTUML_JAR_PATH is required, even though Doxygen is not really rendering the plantuml diagrams. Without the option, plantuml diagrams are ignored by Doxygen.

    • Verbatim text in Doxygen descriptions is supported.

    • Support special Doxygen paragraphs that are similar to AsciiDoc admonitions: \attention, \note, \remark, and \warning.

    • Support special Doxygen paragraphs that contain metadata: \author, \bug, \copyright, \date, \deprecated, \since, and \todo. They are added to the overview table of class-like elements, or the parameter table of functions/methods.

    • Complex tables with cells spanning multiple columns and/or rows and nested tables (1 level) are now supported.

    • Support explicit line breaks in paragraphs.

    • Support LatexMath formulae in Doxygen descriptions. It is required to enable :stem: in the AsciiDoc header to render the formulae.

    • Support images in Doxygen descriptions. Only html type images are shown, also for PDF output. Make sure to include all images in the package containing the xml and specify the asciidoc.image_dir option in contents.toml.

    • Support MarkDown (preprocessed by Doxygen) in Doxygen descriptions. This adds support for: headers, strikethrough, numbered and nested lists, horizontal rulers, and block quotes.

    • Support special characters. This includes 250 characters that Doxygen represents with a separate XML tag.

    • Support HTML headings, preformatted text and other HTML specific styles.

    • Support custom anchors.

    • Support parameter descriptions consisting of multiple paragraphs.

    • Respect output type specific content. Only content for XML and HTML output is used.

    • Support Unicode emoji.


  • Code blocks in descriptions try to respect the language specified in the original code. This includes "unparsed" code blocks. Only if no language is specified, the language of the described element is used.


  • Spaces in code blocks, present as <sp />, are no longer ignored.

  • Actually create links to known exceptions from method/function documentation.

  • #37: When type names contain nested types, and the nested types have namespaces, the short name was incorrectly generated, resulting in incorrect section titles.

  • #35: C++: Support typedefs for function types. Limitation: documentation for the function parameters is missing. A planned refactoring will fix this.

  • #31: Pipe symbols in documentation no longer cause tables to become malformed.

0.7.5 (20 Aug 2021)


  • Provide detailed stack traces for links to missing elements. It should now be clear what commands are causing the links to be inserted, especially when links are inserted as part of another element’s API reference.

  • Provide detailed stack traces when inserting the same element multiple times. It should now be clear whether the element was inserted as part of another element.

  • Support preconditions and postconditions for functions and methods.


  • Provide clearer errors and trace backs for exceptions while parsing AsciiDoc and for internal errors.

  • No longer use fragment files to include generated API reference. Instead, the generated AsciiDoc is directly embedded in the processed AsciiDoc file.

  • Extra AsciiDoc attributes are no longer supported for the insert command.


  • Do not generate empty "Members" section if there are no visible members.

  • Fix running AsciiDoctor on Windows. Thank you r0ckarong!

0.7.4 (25 Mar 2021)


  • Flexible anchors: With multi-page documents it can be hard to keep cross document references working, especially when moving them between files. Using the new anchor command you can create a flexible anchor that will be resolved by AsciiDoxy. Use cross_document_ref with only an anchor to refer to flexible anchors.


  • Remove invalid downloaded packages from the cache. This solves an issue where a failed download was never retried and required a manual purge of the build directory.

  • Verify the contents of downloaded packages with contents.toml. Delete invalid packages from the cache.

  • Copying image files to an existing output directory no longer results in a file collision error. File collision errors now contain more details about the packages causing the collision and also report about files in the output directory that are not part of any package.

  • Provide correct image directory to AsciiDoctor.

0.7.3 (25 Feb 2021)


  • Objective C: Remove debug artefacts. This was causing layout problems in enclosed types.

0.7.2 (24 Feb 2021)


  • Bring back character escaping in links.

  • Improve character escaping in source blocks.

  • [AD-56] Objective C: Fix visibility of enclosed types to match the enclosing type. Objects exposed in a header file are always accessible.

0.7.1 (13 Feb 2021)


  • [AD-59] Support for variables that are shared between included documents.


  • Collisions between files in packages are now warnings by default. Use --warnings-are-errors to change them back to errors. Collisions between files and directories are still fatal errors.


  • #27: xml_subdir and include_subdir should not be mandatory in the package specification if packages with contents.toml are used.

  • #28: C++: support constexpr functions and constructors.

  • Changes to the insertion filter in included documents will no longer affect parent documents.

  • Objective C: Do not append enclosing type to full name of nested types.

  • Improve escaping of names in links.

0.7.0 (31 Dec 2020)


  • Infrastructure for transcoding documentation from one to another language.

  • Swift: [AD-28] Generating Swift documentation based on Objective C source code.

  • Kotlin: [AD-27] Generating Kotlin documentation based on Java source code.

  • [AD-15] Allow forcing to embed an included file in multipage mode.

  • [AD-37] Show members for other visibility levels than public. By default only public and protected members are shown. Use filter to change.

  • [AD-32] New package format with contents metadata file. The contents file specifies whether the package contains AsciiDoc includes or reference, and in what subdirectory. It can now also include images that need to be included to the output.

  • [AD-32] A directory containing images to include can be specified using --image-dir.

  • [AD-11] The usage documentation has been separated into a getting started guide and reference documentation.


  • Argument leveloffset in include now supports None to prevent adding leveloffset in the generated AsciiDoc.

  • [AD-32] By default the directory containing the input file is not copied to the intermediate build directory. Use --base-dir to enable copying of additional include files.

  • [AD-32] cross_document_ref and include support a new package_name keyword to point to files in packages. For new packages with a contents metadata file this keyword is mandatory. If the package specifies a root document, the filename is optional now.

  • [AD-32] For cross_document_ref the anchor and link_text arguments are now keyword only. For backwards compatibility api.cross_document_ref is still supports the old syntax.

  • [AD-32] For include the leveloffset, link_text, and link_prefix arguments are now keyword only. For bacwards compatibility api.include still supports the old syntax.

  • [AD-32] Multiple packages supplying the same file is now an error.

  • [AD-54] If no anchor or link_text is given, the title of the document is used for the link created by cross_document_ref. If the title cannot be read, the file name stem is used.

  • [AD-54] If no link_text is given, the title of the document is used for the link created by include in multipage mode. If the title cannot be read, the file name stem is used.

  • [AD-42] The api. prefix for commands is no longer needed. It will be deprecated in a future version. The api.link_<kind> and api.insert_<kind> commands are also deprecated and not available without the api. prefix.


  • [AD-35] Improve handling of complex closures.

  • Objective C: Support __autoreleasing suffix.

  • Including files in parent directories no longer raises an exception.

  • Files and directories provided on the command-line are validated before use.

  • [AD-55] Insert anchors at the top of includes in singlepage mode to make cross document references without anchors work.

0.6.3 (1 Nov 2020)


  • [AD-33] Actually allow filtering of inner classes by visibility.

  • [AD-46] Always fall back to original name if type parsing fails.

  • [AD-48] Java: Support unmangled annotations.

0.6.2 (22 Sep 2020)


  • C++: [AD-10] Support const methods.

  • C++: Show destructors and operators for classes.

  • [AD-8] Support default values for parameters.


  • C++: [AD-34] Hide default and deleted members.

  • Correctly detect include file for free functions.

  • [AD-33] Inner types can now be filtered by visibility (only public and protected for now).

0.6.1 (27 Jul 2020)


  • [AD-18] Basic support for Java type annotations.

  • Extend 'file_names' option for .toml files to support 'version' and 'name' interpolation.


  • Java constants are now described correctly.

0.6.0 (26 Jun 2020)


  • [AD-4] Multi-page Table of Contents.


  • [AD-1] Complete redesign of the type parser. The type parser is now token based instead of using regular expressions.

  • [AD-1] The new type parser is more strict and will issue warnings when a type is considered malformed. These warnings will not trigger an error when --warnings-are-errors is enabled.

  • [AD-2] Improve formatting of method parameters. Each parameter is put on its own line. The first parameter is put on a separate line if the definition gets too long.

  • [AD-3] Loading API reference using a package spec is no longer required. The --spec-file option is no longer mandatory. This way you can generate any AsciiDoc file with python code, without generating API reference documentation.

  • [AD-5] When using api.link the first match from an overload set is returned, instead of throwing an error. This can be disabled by using allow_overloads=False. api.insert still requires a perfect match.

  • [AD-29] Rename multi_page and multi-page to multipage. This is a breaking change for the command-line options and api.include.


  • Issue #9 - std::function types with function arguments are now fully parsed.

  • [AD-1] Many parsing issues for types have been addressed in the new type parser.

0.5.5 (8 Jun 2020)


  • Support for HTML/markdown tables in description parser.

0.5.4 (21 May 2020)


  • Additional arguments for api.include and api.insert are passed as attributes of the include directive.

  • Improved performance in resolving references and looking up elements to link to and insert.


  • Matching elements in the same namespace are now preferred over elements in a different namespace. Only if all matches are in a parent namespace, the match will be ambiguous.

  • For types directly included in a namespace the include file is now present.

  • C++ functions that are inserted directly, so not as part of an enclosing type, have a section header and include file.

  • Nested python type hints are now detected and shown in the documentation.

0.5.3 (16 May 2020)


  • Allow filtering what members, enum values, inner classes, and exceptions get included when using api.insert().

  • Show progress bars for long running tasks.

  • Support for documenting python code with the help of doxypypy.

  • Specify a required version of AsciiDoxy in the adoc files.


  • Default log level decreased to warnings.

0.5.2 (24 Apr 2020)


  • Support for free functions in C++

0.5.1 (22 Apr 2020)


  • Added option multi\_page\_link to include() method, so an included adoc file is generated but not linked to in multi-page mode.

0.5.0 (21 Apr 2020)


  • When api.insert or api.link is ambiguous, all matching candidates are shown.


  • Links that are part of an inserted element are also considered when looking for dangling links.


  • Report full error information when collection fails.

0.4.3 (2 Apr 2020)


  • Nested enums are no longer ignored in Java.

  • Fix enum template for Java. Descriptions are now complete and in the right column.

0.4.2 (30 Mar 2020)


  • Ignore friend declarations for C++.

  • Improve handling of Java generics.

  • Improve type handling for Objective C.

0.4.1 (27 Mar 2020)


  • Disambiguate function overloads (and other callables) based on the types of the parameters.


  • Search by name with an originating namespace now also finds partial namespace overlaps.

  • Correctly take the originating namespace into account when resolving type references.

0.4.0 (19 Mar 2020)


  • Unknown command line options are now forwarded to AsciiDoctor.

  • New collect module. Uses a package specification file to get Doxygen XML files and other include files from both remote (HTTP) locations and the local file system.

  • Support for generating PDF files.


  • Option -a linkcss is no longer provided to AsciiDoctor by default. You need to add it to the command line invocation of AsciiDoxy if needed.

  • Command line parameters are updated to use the collect module instead of Artifactory.

  • AsciiDoxy is now licensed under the Apache 2.0 license.

  • Code style has been updated to match PEP-008, enforced by yapf.

  • Docstrings have been updated to match Google style.

  • All TomTom proprietary material has been removed. It is replaced by material under the Apache 2.0 license.

0.3.4 (4 Mar 2020)


  • Support for enums in Java

0.3.3 (10 Feb 2020)


  • Support for downloading and extracting of multiple archive files per package


  • Archives are downloaded to download directory

  • The documentation is now built from an intermediate directory

0.3.2 (26 Feb 2020)


  • Prevent infinite loop on unrecognized function pointer type.

0.3.1 (20 Feb 2020)


  • Support for nested classes in Java and C++

0.3.0 (5 Feb 2020)


  • Argument --multi-page to generate separate page for each document included by api.include() call

0.2.2 (3 Feb 2020)


  • Support for Java interfaces.

0.2.1 (15 Jan 2020)


  • Argument --force-language to force the language used for reading Doxygen XML files. This is currently required to properly interpret Objective C header files.

  • Support for Objective-C typedefs and blocks.


  • Try to use the detailed description if there is no brief description.


  • Debug output is now valid, indented, JSON.

  • Objective C types with a space are now correctly detected.

  • Type resolving is not limited to just classes.

  • Do not prepend header file name to Objective C types that are members of files only.

  • Remove spurious spaces in method argument list when the argument has no name.

0.2.0 (23 Dec 2019)


  • Short names are now default, use full_name to get the fully qualified name again.

  • Parameters for link, insert, link_*, and insert_* have changed. The language and kind are no longer mandatory. They will be deduced if there is only one element with the specified name. An error is raised if there are multiple matches. Only name can be passed as positional argument now.


  • Remove surrounding whitespace for types and parameters. This caused incorrect rendering of monospace text.

  • C++: Include enclosed structs.


  • The short_name argument for linking to documentation. This is now the default.

0.1.4 (12 Dec 2019)


  • Support inheritance in template files.

  • Support for C++ interfaces (Doxygen concept).

0.1.3 (14 Nov 2019)


  • Show required include file for C++ and Objective C types.


  • Static methods are separated from normal methods for Java.

  • Class methods are separated from instance methods for Objective C.


  • Indentation of Objective C methods was off when the return type contained a link.

  • Variables were missing from the overview of C++ structs.

  • Decode templates and input document using UTF-8.

  • Ignore Objective C methods marked NS_UNAVAILABLE.

0.1.2 (04 Nov 2019)


  • Support for C++ structs.

  • Overview table for compound members.

  • Include make in the Docker image.


  • Show enclosed typedefs in C++ classes and structs.

  • Improved formatting.

  • Clean up extra whitespace.

0.1.1 (04 Nov 2019)


  • Fix publishing Docker image on CI.

0.1.0 (22 Oct 2019)

  • First internal release.