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

Commands

Inserting API reference

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

${insert(<name>,
         [kind=<kind>,]
         [lang=<language>,]
         [leveloffset=<leveloffset>,]
         [template=<template name>])}

The insert method takes the following arguments:

name: Name of the element to insert. This can be the fully qualified name, or if a namespace is set, a relative name.
lang: Optional. Name of the programming language.
kind: Optional. Kind of element to insert.
leveloffset: Optional. Offset for the headers in the reference from the top level of the current file. Defaults to +1. Provide None to not set the offset.
template: Experimental. Optional. Alternative template to use for generating the API documentation.

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.

Examples

${insert("MyNamespace::MyClass")}                                    (1)
${insert("com.tomtom.Class", leveloffset="+2")}                      (2)
${insert("com.tomtom.Class", kind="class")}                          (3)
${insert("MyNamespace::FreeFunction", lang="c++")}                   (4)

1	Insert API reference for the element named `MyNamespace::MyClass`.
2	Insert API reference for the element named `com.tomtom.Class` using an alternative level offset for the headers in the API reference.
3	Insert API reference for the class named `com.tomtom.Class`. Elements of other types are ignored.
4	Insert API reference for the C++ element named `MyNamespace::FreeFunction`. Other languages are ignored.

Filtering what is inserted

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

${insert(...,
         [members=<filter_spec>,]
         [exceptions=<filter_spec>])}

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.

Global filters

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

${filter([members=<filter_spec>,]
         [exceptions=<filter_spec>])}

The global filter applies to every call to 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.

Combining filter specifications

When an insert call contains additional filter specifications, these specifications are added to the end of the global filter specifications:

${filter(members=["add", "update"])}
${insert("name", members=["remove"])}

# Is equal to
${insert("name", members=["add", "update", "remove"])}

Filters added in insert are always added to the end. If there is no corresponding global filter specification, it is treated as a new filter, and NONE or ALL is prepended if needed.

The global filter can be overridden for some calls to insert. Then only the explicit filter specifications on that call are used:

${insert(...,
         ignore_global_filter=True,
         [members=<filter_spec>,]
         [exceptions=<filter_spec>])}

Linking to API reference

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

${link(<name>,
       [kind=<kind>,]
       [lang=<language>,]
       [text=<alt_text>,]
       [full_name=<True/False>,]
       [allow_overloads=<True/False>])}

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

name: Fully qualified name of the element to insert.
lang: Name of the programming language.
kind: Kind of element to insert.
text: Alternative text to use for the link.
full_name: Use the fully qualified name of the referenced element.
allow_overloads: True to link to the first match in an overload set.

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.

Function or method overloads

In languages that support overloading functions, methods or other callables, the name alone is not sufficient to select the correct element to link to or to insert. By default AsciiDoxy will create a link to the first member of the overload. In case you need to link to a specific overload the exact list of types of the parameters can be provided to select the right element.

The list of parameter types should be specified in parentheses after the function name:

${link("MyFunction(int, std::string)")}

Empty parentheses indicate the function should accept no parameters:

${link("MyFunction()")}

If no parentheses are given, the parameters are ignored. If there are multiple overloads, AsciiDoxy will not be able to pick one:

${link("MyFunction")}

Examples

${link("MyNamespace::MyClass")}                            (1)
${link("MyNamespace::MyClass", lang="c++")}                (2)
${link("com.tomtom.Class.Method", full_name=True)}         (3)
${link("MyNamespace::FreeFunction", text="FreeFunction")}  (4)
${link("MyNamespace::MyClass", kind="class")}              (5)
${link("MyNamespace::MyClass", kind="class", lang="c++")}  (6)

1	Link to any element called `MyNamespace::MyClass`.
2	Link to any C++ element called `MyNamespace::MyClass`. Other languages are ignored.
3	Link to `com.tomtom.Class.Method` and use the fully qualified name for the link text.
4	Link to `MyNamespace::FreeFunction` and use "FreeFunction" for the link text.
5	Link to class `MyNamespace::MyClass`. Ignore other kinds of elements.
6	Link to C++ class `MyNamespace::MyClass`. Ignore other kinds of elements and languages.

Including other AsciiDoc files

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

Perform preprocessing on the included AsciiDoc files. When using the normal include directive, AsciiDoxy will not preprocess the included file.
Extend the include functionality, for example with multi-page support.

${include(<file_name>,
          [package_name=<package name>,]
          [leveloffset=<offset>,]
          [link_text=<text>,]
          [link_prefix=<prefix>,]
          [multipage_link=<bool>,]
          [always_embed=<bool>,]
          [...])}

file_name: Relative path to the file to include. Absolute paths are not allowed.

When package_name is provided, the path is relative to the root of the package. Otherwise, it is relative to the current file.
package_name: Package containing the file to include. Defaults to the current package.
leveloffset: Offset for the headers in the included file from the top level of the current file. Defaults to +1.

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:

link_text: Text for the link to insert in multi-page mode. By default the title of the included document is used, or if no title is detected the file name stem.
link_prefix: Text to insert before the link in multi-page mode. Use this to create for example a numbered list of links.
multipage_link: By default a link is inserted in multi-page mode. Set this to False to omit inserting the link. The included file is still processed. Use [cross_referencing] to insert a link elsewhere in the document.
always_embed: Always embed the included file in the current document, even if multipage mode is enabled.

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.

Examples

${include("component/reference.adoc")}                                           (1)
${include("../reference.adoc", leveloffset="+3")}                                (2)
${include("component/reference.adoc", link_text="Reference", link_prefix=". ")}  (3)
${include("component/reference.adoc", multipage_link=False)}                     (4)

1	Include and process `component/reference.adoc` relative to this file.
2	Include and process `reference.adoc` in the parent directory of this file. Increase the level of the headers by 3.
3	In multi-page mode use the link text "Reference" and prefix with a dot to create a numbered list. In single-page mode the document is embedded.
4	In multi-page mode process the file, but do not create a link to it. In single page mode the document is embedded.

Cross-referencing other AsciiDoc files

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

${cross_document_ref([<file_name>,]
                     [package_name=<package name>,]
                     [anchor=<section-anchor>,]
                     [link_text=<text>])}

file_name: Relative path to the file to link to. Absolute paths are not allowed.

When package_name is provided, the path is relative to the root of the package. Otherwise, it is relative to the current file.
package_name: Package containing the file to link to. Defaults to the current package.
anchor: Anchor to link to.
link_text: Text to use for the link.

When file_name is not provided, a link to a flexible anchor is made.

If link_text is not provided, AsciiDoxy tries to select the most appropriate text for the link. It will use the first available of:

The value of anchor if provided.
The first title found in the linked document.
The stem of the file name being linked.

Examples

${cross_document_ref("component/component_a.adoc")}                      (1)
${cross_document_ref("component/component_a.adoc", anchor="section-1")}  (2)
${cross_document_ref("component/component_a.adoc", anchor="section 1",   (3)
                     link_text="Component A - Section 1")}

1	Insert a link where the text comes from the title of the linked document.
2	Insert a link with text "section-1".
3	Insert a link with text "Component A - Section 1".

Setting default programming language

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

${language(<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.

language: Language to use as default, or None to reset.

Examples

${language("cpp")}  (1)
${language("c++")}  (2)
${language("java")} (3)
${language(None)}   (4)

1	Set the default language to C++.
2	Set the default language to C++. Alternative language name.
3	Set the default language to Java.
4	Remove the default language.

Transcoding

In some ecosystems multiple languages can be used together. Elements written in one language can directly be used in the other language. The compiler or interpreter makes sure calls are translated appropriately. AsciiDoxy supports generating documentation that shows how to use elements written in one language in the other language. It is called "transcoding".

${language(<language>, source=<source_language>)}

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

language: Language to use for all following insert and link directives.
source: Language to transcode elements from if the element cannot be found for language. None to disable transcoding.

Examples

${language("kotlin", source="java")}  (1)
${language("swift", source="objc")}   (2)
${language("java", source=None)}      (3)

1	Insert elements as Kotlin elements. Transcode from Java if the element is not found.
2	Insert elements as Swift elements. Transcode from Objective C if the element is not found.
3	Disable transcoding, use Java as default language.

Search namespace

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 namespace sets the search namespace.

${namespace(<namespace>)}

namespace: Namespace to start the search from, or None to reset.

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.

Examples

${namespace("org.asciidoxy.parser")}  (1)
${namespace("asciidoxy::example")}    (2)
${namespace(None)}                    (3)

1	Search in the Java package `org.asciidoxy.parser`.
2	Search in the C++ namespace `asciidoxy::example`.
3	Only allow fully qualified names from now on.

Required version

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.

${require_version(<specifier>)}

specifier: One or more comma-separated version specifiers matching the PEP 440 standard.

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

Examples

${require_version("==0.5.3")}       (1)
${require_version("~=0.5.3")}       (2)
${require_version(">=0.5.3")}       (3)
${require_version(">=0.5.3,<0.7")}  (4)

1	Require version 0.5.3. Allow no other versions.
2	Require version 0.5.3 and any newer version that is compatible. In this case patch increments are allowed, but minor and major increments are not.
3	Require version 0.5.3 and any newer version, including versions with breaking changes.
4	Require version 0.5.3 and above, but below version 0.7.

Multi-page table of contents

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.

${multipage_toc([side=<left/right>])}

side: Side of the page to put the table of contents, similar to the AsciiDoc option. Defaults to the left side.

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:

:docinfo: private

Examples

${multipage_toc()}              (1)
${multipage_toc(side="left")}   (2)
${multipage_toc(side="right")}  (3)

1	Insert a multi-page ToC on the left side of the document (default).
2	Same as above, but with explicit side.
3	Insert a multi-page ToC on the right side of the document.

Flexible anchors

In multi-page mode it can be hard to keep track of references to other documents. Especially when moving them between files. The anchor command allows you to insert a flexible anchor that gets resolved by AsciiDoxy. You can refer to flexible anchors by using cross_document_ref with just an anchor.

${achor(<name>, [link_text=<left/right>])}

name: Name of the anchor. Uses this name to refer to it. The name must be unique accross all included documents.
link_text: Optionally a text to use for any links to the flexible anchor. If no text is provided, either the link_text provided to cross_document_ref is used, or the name.

Examples

${anchor("my-anchor")}                                       (1)
${anchor("other-anchor", link_text="superduper text here")}  (2)

${cross_document_ref(anchor="my-anchor", link_text="here")}  (3)
${cross_document_ref(anchor="other-anchor")}                 (4)

1	Insert an anchor named `my-anchor` without a default link text.
2	Insert an anchor named `other-anchor` with a default link text.
3	Insert a reference to the first anchor and override the text for the link.
4	Insert a reference to the second anchor and use the default link text from the anchor.

Reference

Api

class asciidoxy.generator.asciidoc.Api

Methods to insert and link to API reference documentation from AsciiDoc files.

Methods	`filter` Set a default filter used when inserting API reference documentation. `insert` Insert API reference documentation. `link` Insert a link to API reference documentation. `cross_document_ref` AsciiDoc cross-document reference. `anchor` Create a flexible anchor. `include` Include another AsciiDoc file, and process it to insert API references. `language` Set the default language for all following commands. `namespace` Set the namespace to start searching for elements for all following commands. `require_version` Require a specific version of AsciiDoxy. `multipage_toc` Insert a table of contents for multipage documents.

Methods

filter: Set a default filter used when inserting API reference documentation.
insert: Insert API reference documentation.
link: Insert a link to API reference documentation.
cross_document_ref: AsciiDoc cross-document reference.
anchor: Create a flexible anchor.
include: Include another AsciiDoc file, and process it to insert API references.
language: Set the default language for all following commands.
namespace: Set the namespace to start searching for elements for all following commands.
require_version: Require a specific version of AsciiDoxy.
multipage_toc: Insert a table of contents for multipage documents.

Members

filter

def filter(self,
           members: *Optional[FilterSpec] = None,
           exceptions: Optional[FilterSpec] = None) -> str

Set a default filter used when inserting API reference documentation.

The filter controls which members of an element are inserted. Only the members matching the filter are inserted, the others are ignored. Depending on the exact type of element inserted, its members and/or exceptions can be filtered.

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.

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.

Parameters	`members: Optional[FilterSpec]` Filter to apply to members of a compound. Supports filtering on `name`, `kind`, and `prot`ection level. Default value: `None` `exceptions: Optional[FilterSpec]` Filter to apply to exceptions thrown by a member. Supports filtering on the `name` of the exception type only. Default value*: `None`
Returns	`str` An empty string.

Parameters

members: *Optional[FilterSpec]: Filter to apply to members of a compound. Supports filtering on name, kind, and protection level.

Default value: None
exceptions: Optional[FilterSpec]: Filter to apply to exceptions thrown by a member. Supports filtering on the name of the exception type only.

Default value: None

Returns

str: An empty string.

insert

def insert(self,
           name: str,
           kind: *Optional[str] = None,
           lang: Optional[str] = None,
           members: Optional[FilterSpec] = None,
           exceptions: Optional[FilterSpec] = None,
           ignore_global_filter: bool = False,
           leveloffset: str = "+1",
           template: Optional[str] = None) -> str

Insert API reference documentation.

Only name is mandatory. Multiple names may match the same name. Use kind and lang to disambiguate.

For the supported format of the filter arguments see Api.filter().

Parameters	`name: str` Fully qualified name of the object to insert. `kind: Optional[str]` Kind of object to generate reference documentation for. Default value: `None` `lang: Optional[str]` Programming language of the object. Default value: `None` `members: Optional[FilterSpec]` Filter to apply to members of a compound. Supports filtering on `name`, `kind`, and `prot`ection level. Default value: `None` `exceptions: Optional[FilterSpec]` Filter to apply to exceptions thrown by a member. Supports filtering on the `name` of the exception type only. Default value: `None` `ignore_global_filter: bool` True to ignore the global filter set with `Api.filter()`. False to apply the filters on top of the global filter. Default value: `False` `leveloffset: str` Offset of the top header of the inserted text from the top level header of the including document. Default value: `"+1"` `template: Optional[str]` Experimental* Alternative template to use when inserting the reference documentation. Default value: `None`
Returns	`str` AsciiDoc text to include in the document.

Parameters

name: str: Fully qualified name of the object to insert.
kind: *Optional[str]: Kind of object to generate reference documentation for.

Default value: None
lang: Optional[str]: Programming language of the object.

Default value: None
members: Optional[FilterSpec]: Filter to apply to members of a compound. Supports filtering on name, kind, and protection level.

Default value: None
exceptions: Optional[FilterSpec]: Filter to apply to exceptions thrown by a member. Supports filtering on the name of the exception type only.

Default value: None
ignore_global_filter: bool: True to ignore the global filter set with Api.filter(). False to apply the filters on top of the global filter.

Default value: False
leveloffset: str: Offset of the top header of the inserted text from the top level header of the including document.

Default value: "+1"
template: Optional[str]: Experimental Alternative template to use when inserting the reference documentation.

Default value: None

Returns

str: AsciiDoc text to include in the document.

link

def link(self,
         name: str,
         kind: *Optional[str] = None,
         lang: Optional[str] = None,
         text: Optional[str] = None,
         full_name: bool = False,
         allow_overloads: bool = True) -> str

Insert a link to API reference documentation.

Only name is mandatory. Multiple names may match the same name. Use kind and lang to disambiguate.

Parameters	`name: str` Fully qualified name of the object to link to. `kind: Optional[str]` Kind of object to link to. Default value: `None` `lang: Optional[str]` Programming language of the object. Default value: `None` `text: Optional[str]` Alternative text to use for the link. If not supplied, the object name is used. Default value: `None` `full_name: bool` Use the fully qualified name of the object for the link text. Default value: `False` `allow_overloads: bool` Link to the first match in an overload set. Enabled by default. Default value*: `True`
Returns	`str` AsciiDoc text to include in the document.

Parameters

name: str: Fully qualified name of the object to link to.
kind: *Optional[str]: Kind of object to link to.

Default value: None
lang: Optional[str]: Programming language of the object.

Default value: None
text: Optional[str]: Alternative text to use for the link. If not supplied, the object name is used.

Default value: None
full_name: bool: Use the fully qualified name of the object for the link text.

Default value: False
allow_overloads: bool: Link to the first match in an overload set. Enabled by default.

Default value: True

Returns

str: AsciiDoc text to include in the document.

cross_document_ref

def cross_document_ref(self,
                       file_name: Optional[str] = None,
                       package_name: *Optional[str] = None,
                       anchor: Optional[str] = None,
                       link_text: Optional[str] = None) -> str

AsciiDoc cross-document reference.

Since AsciiDoxy in multi-page mode generates intermediate AsciiDoc files and process them with AsciiDoctor in order to create final output document(s) the direct AsciiDoc syntax (i.e. <<file_name#anchor,link_text>>) doesn’t work. You must use this method instead.

Parameters	`file_name: Optional[str]` Name of the file. If `package_name` is specified, it must be relative to the root of the package. Otherwise, it is relative to the current document. Absolute paths are not supported. Default value: `None` `package_name: Optional[str]` Name of the package containing the file. If not specified, the file must come from the same package. Default value: `None` `anchor: Optional[str]` Anchor to the referred section in the referred AsciiDoc document. If no `file_name` or `package_name` is given it refers to a flexible anchor as inserted by `anchor`. Default value: `None` `link_text: Optional[str]` Text for the link to insert. If not provided, either the anchor, the title of the document or the name of the file is used. Default value*: `None`
Returns	`str` AsciiDoc cross-document reference.
Throws	`InvalidApiCallError` Incorrect argument or argument combinations are used. `MissingPackageError` The specified package is not available. `MissingPackageFileError` The specified file name is not available in the package. `UnknownAnchorError` The `anchor` is not a known flexible anchor and no `file_name` or `package_name` is provided.

Parameters

file_name: Optional[str]: Name of the file. If package_name is specified, it must be relative to the root of the package. Otherwise, it is relative to the current document. Absolute paths are not supported.

Default value: None
package_name: *Optional[str]: Name of the package containing the file. If not specified, the file must come from the same package.

Default value: None
anchor: Optional[str]: Anchor to the referred section in the referred AsciiDoc document. If no file_name or package_name is given it refers to a flexible anchor as inserted by anchor.

Default value: None
link_text: Optional[str]: Text for the link to insert. If not provided, either the anchor, the title of the document or the name of the file is used.

Default value: None

Returns

str: AsciiDoc cross-document reference.

Throws

InvalidApiCallError: Incorrect argument or argument combinations are used.
MissingPackageError: The specified package is not available.
MissingPackageFileError: The specified file name is not available in the package.
UnknownAnchorError: The anchor is not a known flexible anchor and no file_name or package_name is provided.

anchor

def anchor(self,
           name: str,
           link_text: *Optional[str] = None) -> str

Create a flexible anchor.

In multi-page mode it may be hard to move content containing anchors between files. All references to the anchor need to be updated to point to the correct files. This command allows you to create flexible anchors.

In single-page mode, this will result in a normal AsciiDoc anchor. In multi-page mode it will also make sure that other files can refer to the anchor without having to specify the file containing it.

Parameters	`name: str` Name of the anchor. Use this name in `cross_document_ref` to refer to the `link_text: Optional[str]` Optional text to use in links to the anchor. Default value*: `None`
Returns	`str` AsciiDoc anchor.
Throws	`DuplicateAnchorError` An anchor with the specified name already exists.

Parameters

name: str: Name of the anchor. Use this name in cross_document_ref to refer to the
link_text: *Optional[str]: Optional text to use in links to the anchor.

Default value: None

Returns

str: AsciiDoc anchor.

Throws

DuplicateAnchorError: An anchor with the specified name already exists.

include

def include(self,
            file_name: str,
            package_name: *Optional[str] = None,
            leveloffset: str = "+1",
            link_text: str = "",
            link_prefix: str = "",
            multipage_link: bool = True,
            always_embed: bool = False,
            asciidoc_options: **) -> str

Include another AsciiDoc file, and process it to insert API references.

If the output format is multi-paged, the method will by default cause generation of separate output document for the included AsciiDoc document and optional insertion of link referring to the document.

Parameters	`file_name: str` Name of the file. If `package_name` is specified, it must be relative to the root of the package. Otherwise, it is relative to the current document. Absolute paths are not supported. `package_name: Optional[str]` Name of the package containing the file. If not specified, the file must come from the same package. Default value: `None` `leveloffset: str` Offset of the top header of the inserted text from the top level header of the including document. Default value: `"+1"` `link_text: str` Text of the link which will be inserted when the output format is multi-paged. By default the document title (if found) or file name stem is used. Default value: `""` `link_prefix: str` Optional text which will be inserted before the link when the output format is multi-paged. It can be used for example to compose a list of linked subdocuments by setting it to ". ". Default value: `""` `multipage_link: bool` True to include a link in a multipage document (default). Otherwise the separate document is generated but not linked from here. Default value: `True` `always_embed: bool` True to always embed the contents in the current document, even in multipage mode. Default value: `False` `asciidoc_options: *` Any additional option is added as an attribute to the include directive in single page mode.
Returns	`str` AsciiDoc text to include in the document.
Throws	`InvalidApiCallError` Incorrect argument or argument combinations are used. `MissingPackageError` The specified package is not available. `MissingPackageFileError` The specified file name is not available in the package.

Parameters

file_name: str: Name of the file. If package_name is specified, it must be relative to the root of the package. Otherwise, it is relative to the current document. Absolute paths are not supported.
package_name: *Optional[str]: Name of the package containing the file. If not specified, the file must come from the same package.

Default value: None
leveloffset: str: Offset of the top header of the inserted text from the top level header of the including document.

Default value: "+1"
link_text: str: Text of the link which will be inserted when the output format is multi-paged. By default the document title (if found) or file name stem is used.

Default value: ""
link_prefix: str: Optional text which will be inserted before the link when the output format is multi-paged. It can be used for example to compose a list of linked subdocuments by setting it to ". ".

Default value: ""
multipage_link: bool: True to include a link in a multipage document (default). Otherwise the separate document is generated but not linked from here.

Default value: True
always_embed: bool: True to always embed the contents in the current document, even in multipage mode.

Default value: False
asciidoc_options: **: Any additional option is added as an attribute to the include directive in single page mode.

Returns

str: AsciiDoc text to include in the document.

Throws

InvalidApiCallError: Incorrect argument or argument combinations are used.
MissingPackageError: The specified package is not available.
MissingPackageFileError: The specified file name is not available in the package.

language

def language(self,
             lang: Optional[str],
             source: *Optional[str] = None) -> str

Set the default language for all following commands.

Elements will then only be inserted for that language, and other languages are ignored. The language can still be overridden with the lang keyword. Files included after this command will also be affected.

Optionally, a different language can be used as the source of the API reference. If an element is inserted that does not exist in the target lang, it is automatically transcoded from the source language. This feature is only available for a limited set of languages.

Params

lang The new default language, or None to reset. source Language to transcode from if an element is not available in the selected language. Only available for limited combinations.

Parameters	`lang: Optional[str]` `source: Optional[str]` Default value*: `None`
Returns	`str`
Throws	`InvalidApiCallError` The `source` language needs to be different from `lang`, and `lang` is required when `source` is specified.

Parameters

lang: Optional[str]
source: *Optional[str]: Default value: None

Returns

str

Throws

InvalidApiCallError: The source language needs to be different from lang, and lang is required when source is specified.

namespace

def namespace(self,
              namespace: Optional[str]) -> str

Set the namespace to start searching for elements for all following commands.

If the element cannot be found in this namespace, it is also searched as a fully qualified name. Files included after this command will also be affected.

Parameters	`namespace: Optional[str]` The namespace to search, or None to reset. The namespace should use the language specific namespace separator and should also include the separator between the namespace and the short name.
Returns	`str`

Parameters

namespace: Optional[str]: The namespace to search, or None to reset. The namespace should use the language specific namespace separator and should also include the separator between the namespace and the short name.

Returns

str

require_version

def require_version(self,
                    specifier: str) -> str

Require a specific version of AsciiDoxy.

If the running version of AsciiDoxy does not match, an exception is thrown and generation stops.

Parameters	`specifier: str` One or more comma-separated version specifiers matching the PEP 440
Returns	`str`

Parameters

specifier: str: One or more comma-separated version specifiers matching the PEP 440

Returns

str

multipage_toc

def multipage_toc(self,
                  side: str = "left") -> str

Insert a table of contents for multipage documents.

Only supported for the HTML backend and when multipage mode is on.

This command needs to be included in the document headers to work. To not break headers when multipage mode is off, it is recommended to add it to the end of the headers.

Parameters	`side: str` Show the multipage TOC at the `left` or `right` side. Default value: `"left"`
Returns	`str`

Parameters

side: str: Show the multipage TOC at the left or right side.

Default value: "left"

Returns

str