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

Packages

Package format

AsciiDoxy supports 2 physical package formats:

A directory on the local file system, or a mounted remote file system.
A tar.gz archive hosted on an HTTP server.

Other archive formats and compressions are not supported at the moment.

Package specification files

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:

packages: Specification of packages to include.
sources: Templates for similar packages.

Packages

The packages section is the only mandatory section. It contains a separate subsection for each package to include. The name of the subsection is the name of the package:

[packages]

[packages.package1]
# Specification of `package1`

[packages.package2]
# Specification of `package2`

A package has a specific type and based on the type different key/value pairs are required. For all types of packages the following key/value pairs are required:

type: The type of the package.

For old-style packages the following key/value pairs are required. For backwards compatibility they can always be specified, even for new-style packages. But in case of new-style packages, they are ignored. New-style packages use Package content files to specify the contents.

xml_subdir: Subdirectory in the root of the package in which all Doxygen XML files are stored.
include_subdir: Subdirectory in the root of the package in which all other include files are stored.

Packages of type local refer to a local directory. They require the following additional key/value pairs:

package_dir: Absolute or relative path to the directory containing the package.

Example:

[packages.local_package]
type = "local"
xml_subdir = "xml"
include_subdir = "adoc"
package_dir = "/path/to/my/package/"

Packages of type http are downloaded from a remote location. They can consist of multiple files, all of which need to be (compressed) tarballs. Each file can contain XML files, include files, or both.

The following additional key/value pairs are required:

url_template: Template for constructing the URL to download the package file from.
file_names: List of file names making up the package.

The following additional key/value pairs are optional:

version: Version number of the package.
login: User name to login to the HTTP server.
password: Password to login to the HTTP server.
login_env: Environment variable containing the user name to login to the HTTP server.
password_env: Environment variable containing the password to login to the HTTP server.

The url_template can contain the following placeholders, that are replaced when creating the URL to download each package file:

{name}: Replaced with the name of the package.
{version}: Replaced with the version of the package.
{file_name}: Replaced with the file name.

When one or more of login, password, login_env, or password_env is provided, they are used to authenticate to the HTTP server. login and password contain the authentication details in plain text in the specification file. It is not recommended to use password.

login_env and password_env contain the name of an environment variable providing the value for respectively login and password. They overrule login and password. If the environment variable is not set, an error will be given. It is possible to combine login with password_env and login_env with password.

If none of login, password, login_env, or password_env are given, the system netrc file is inspected to find authentication settings for the host name.

Example:

[packages]

[packages.package1]
type = "http"
url_template = "https://example.com/{name}/{version}/{file_name}"
xml_subdir = "xml"
include_subdir = "adoc"
version = "12.3.4"
login = "asciidoxy"
password_env = "ASCIIDOXY_PASSWORD"

If no version is specified for the package, the version is retrieved from a version file. The version file is a comma separated values file containing pairs of package names and corresponding versions. It can contain any number of fields, but it is required to have a header containing the names Component name and Version for the columns containing these.

Example:

Component name, Version
package1,3.0.0
package2,4.5.1

Sources

The sources section allows specifying templates for packages. Each template can specify a common "source" of packages. With a source, settings that are duplicated for many packages can be specified only once.

A source section can contain every key/value pair that is allowed for a package. Packages can specify the source they are based on by using the source key/value pair.

When a source is used, the key/value pairs of the source and the package are merged. Values for keys that are present in both the package and the source will be taken from the package. So the package values override source values.

Example:

[sources]

[sources.remote_server]
type = "http"
url_template = "https://example.com/{name}/{version}/{file_name}"
xml_subdir = "xml"
include_subdir = "adoc"

[packages]

[packages.package1]
source = "remote_server"
version = "12.3.4"

Package content files

Each package should describe its contents in a metadata file called contents.toml. This file is used by AsciiDoxy to determine how to use the contents of the package.

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

package: Metadata for the package.
reference: The API reference information contained in the package.
asciidoc: AsciiDoc and other files to be included in AsciiDoc generation.
python: Python scripts to include in AsciiDoc generation.

Package section

The package section contains general metadata for the package. This section is mandatory for all packages. It contains the following key/value pairs:

name: Name of the package. This overrides the name specified in the package specification file.

Reference section

The reference section describes the API reference contained in the package. It is only required if the package contains API reference information. Without this section, API reference information is ignored. It contains the following key/value pairs:

type: The type of API reference information. Currently, only supports doxygen for Doxygen XML format.
dir: Subdirectory inside the package containing the API reference information files.

Asciidoc section

The asciidoc section describes AsciiDoc and other files in the package that can be included in the generated documentation. This section is only required if the package contains files to be included. It can contain the following key/value pairs:

src_dir: (Required) Subdirectory inside the package containing the AsciiDoc and other include files.
image_dir: (Optional) Subdirectory inside the package containing images to be included in the AsciiDoc files. These files are copied to the image directory used for all AsciiDoc files.
root_doc: (Optional) Document to include by default for the package. Used if not specific file in the package is mentioned.

Python section

The python section describes files in the package that are to be included when generating the AsciiDoc files. The subdirectory containing the python files is automatically added to the python path for all files.

dir: (Required) Subdirectory inside the package containing python code to be included in generation.