Changelog

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.

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.

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.

The wheel distribution was missing required CSS files.

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.

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

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.

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.

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.

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!

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.

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

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.

[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.

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.

[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.

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).

[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.

[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.

Support for HTML/markdown tables in description parser.

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.

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.

Support for free functions in C++

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

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.

Nested enums are no longer ignored in Java.

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

Ignore friend declarations for C++.

Improve handling of Java generics.

Improve type handling for Objective C.

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.

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.

Support for enums in Java

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

Prevent infinite loop on unrecognized function pointer type.

Support for nested classes in Java and C++

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

Support for Java interfaces.

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.

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.

Support inheritance in template files.

Support for C++ interfaces (Doxygen concept).

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.

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.

Fix publishing Docker image on CI.