Usage

For extracting documentation from source code, AsciiDoxy relies on Doxygen. You are expected to run Doxygen on your source code, and then provide the path to the generated XML files to AsciiDoxy. It is recommended to set at least the following non-default settings in your Doxyfile when generating the XML.

AsciiDoxy needs to know where to find the XML files containing the API reference documentation. It supports loading these files from a local directory or from a remote HTTP server. Package specification files describe where to collect the XML files.

A single location containing the XML files is called a package. The idea is that each package corresponds to an isolated component that can be included as a separate package. Documentation for separate packages can refer to each other when used in combination.

Packages can contain additional resources like images, example source code, and AsciiDoc files. These resources can be referred to from the input AsciiDoc files.

Package specification files use TOML format. They can contain the following sections:

The original purpose of AsciiDoxy is to insert API reference documentation in AsciiDoc files. Use the api.insert method to insert API reference documentation at the current location.

The insert method takes the following arguments:

Trying to insert an unknown element will result in an error.

When not specifying the language and kind, AsciiDoxy will try to find the element by name, and deduce the kind and language. If there are multiple matching elements, an error is raised.

You can add additional options. These options are added as attributes to the inserted include directive for the API reference fragment. For available attributes see the AsciiDoctor manual.

By default api.insert inserts all contents of the API element. You can control which members, inner classes, enum values, and exceptions get inserted for each call to api.insert.

A filter specification is either a single string, a list of strings, or a dictionary.

A single string is the same as a list of strings with just one item.

A list of strings defines a set of regular expressions to be applied to the name. They are applied in the order they are specified. If the element is still included after all filters have been applied, it is inserted.

Each string can have the following value: NONE:: Exclude all elements. ALL:: Include all elements. <regular expression> or +<regular expression:: Include elements that match the regular expression. -<regular expression>:: Exclude elements that match the regular expression.

If the first string is an include regular expression, an implicit NONE is prepended, if the first string is an exclude regular expression, an implicit ALL is prepended.

Some filters support filtering on other properties than the name. By default they only filter on the name. To filter the other properties use a dictionary, where the key is the name of the property, and the value is a string or list of strings with the filter.

A global filter can be set that applies to every api.insert after it is set using api.filter.

The global filter applies to every call to api.insert in the same file, after it is set. It also applies to any file included after it is set.

Filters can be overridden in included files. At the end of the file, the original filter is restored.

Use api.link to insert a link to an API reference element.

By default the short name of the element is used as the text of the link.

A warning is shown if the element is unknown, or is not inserted in the same document using the insert method. There is a command-line option to throw an error instead.

When not specifying the language and kind, AsciiDoxy will try to find the element by name, and deduce the kind and language. If there are multiple matching elements, an error is raised.

AsciiDoc has the include directive to embed other AsciiDoc files in the current file. AsciiDoxy extends this directive with its api.include method for 2 reasons:

In single-page mode, the default, the file to include is preprocessed by AsciiDoxy. Then a normal include directive is inserted pointing to the preprocessed file. This embeds the file in the same output document.

In multi-page mode, the preprocessed file is not embedded. Instead, a separate output file is generated, and a link to that file is inserted. The format of the link is controlled with additional arguments:

You can add additional options. These options are added as attributes to the inserted include directive for the API reference fragment. For available attributes see the AsciiDoctor manual.

In multi-page mode, normal cross references to anchors in included files do not work. A link to the appropariate file needs to be created. For this there is api.cross_document_ref.

When all documentation in a file is for the same programming language, you can set the default language to use for every command using api.language.

Other languages will be ignored, unless overridden with a lang argument. This setting also applies to all files included afterwards, but resets and the end of the current file.

By default AsciiDoxy searches for API elements using their fully qualified name. For languages that support namespaces, a search namespace can be set to start looking for elements using a relative name. The api.namespace sets the search namespace.

AsciiDoxy tries to search the same way the program language would. It searches the selected namespace, but also every namespace above it, until it finds a match. This includes the root namespace if nothing is found earlier.

Your documentation may require features of a specific version of AsciiDoxy. It may also use features that are changed in a future version. To make sure your documentation is always generated with a compatible version of AsciiDoxy, you can specify a required version or version range.

The version specifiers follow PEP 440, which is the same standard for specifying python package versions installed with pip.

In multi-page mode the table of contents generated by AsciiDoctor only contains the sections for each specific page. The contents of other pages in the tree are not visible. You can add an extra table of contents listing each separate page.

In the table of contents, only the first document title encountered in each AsciiDoc file is used. For documents having multiple titles, like the book type, the other titles are ignored.

It can be combined with the normal AsciiDoctor table of contents. If both tables are configured to appear on the same side, they will hide eachother, so make sure you choose different sides.

The command should be included in the document header. If that is not possible, make sure the document header contains at least: