User Guide

Concepts

Entities

Throughout the docs (and the code,) the term “entity” is used to refer to any object that can be documented by Doxygen. This includes C language constructs, such as functions, structures, macros, as well as aggregations like files and Doxygen groups.

Kinds

Entities have a “kind”, which is corresponds to Doxygen’s attribute of the same name. Valid kinds are: class, struct, union, exception, file, namespace, group, page, example, dir, define, property, variable, typedef, enum, enumvalue, function, friend.

Not all kinds are currently supported.

Todo

Some important doxygen constructs may be missing.

References

The standard way to refer to C language constructs in antidox is by file_path::entity_name, (called a target in antidox terms) where file_path is base name of the file, along with enough directory components to make the path unique (similar to the default settings in Doxygen.)

Note that while a target should correspond to only one code entity, the same entity can be described by different targets. For example a/b.h::f and b.h::f.

The target for a file has the form file_path::*.

For entities that are not C-language elements (for example, a Doxygen group), the “bracket syntax” [name] or kind[name] can be used. In the former the name must be unique among all kinds of entities, while the latter allows disambiguation by specifying the kind.

Inside a doxy:c directives (i.e, when calling doxy:c or doxy:r inside the body, or via a a template) the extension will try to resolve ambiguous names by prioritizing entities that are children of the one currently being documented.

Directives, roles and domains

Directives and roles are contained in an doxy domain.

.. doxy:c::

This directive inserts the documentation corresponding to a doxygen-documented entity. The entity is specified either as a target string:

.. doxy:c:: file.h::identifier

or, if it is not a C-language element (for example, a Doxygen group) by using the syntax:

.. doxy:c:: kind[name]

Where kind is optional- if it is not given, then name should be unique. See directives.ENTITY_RE for details on the reference format.

There is nothing hardcoded about the reST nodes that get created. Everything, including index and cross reference creation is controlled by the XSL template, see Customization.

The following options are accepted:

hidedef
For macros and variables, do not show the definition.
hideloc
Do not print the location in the source code of the definition.
noindex
Do not add index entries. This options is inherited by children included automatically by the :children: option.
hidedoc
Do not render the text of the documentation. This is useful if you want to replace the description with your own text in the reST source.
children
Include documentation for the given child elements. This option may be empty, in which case the default is to include all children whose kind is different from the current element.
no-children
Exclude the selected children. By default if this option is empty, it forces all children to be excluded.

Children are normally specified by name. The default inclusion behavior can be overridden by responding the antidox-include-children event.

:doxy:r:

Insert a cross reference to an entity documented with doxy:c. As with other Sphinx cross-reference roles, the link can be assigned an explicit title by using the syntax :ref:`Link title <reference>`.

The format for the reference is the same as in doxy:c. Additionally, a Doxygen refid can be directly specified by prefixing it with !. This is meant to facilitate conversion of Doxygen’s <ref> nodes to Sphinx references.

If an explicit link title is not given, it is derived from the reference. If the reference is prefixed by ~ (tilde) then the path component will not be part of the title (e.g. file.h::X::Name will render as Name).

When customizing the template, it is recommended to use this directive to convert Doxygen’s <ref> elements.

Configuration variables

antidox_doxy_xml_dir

Directory where the doxygen XML files are to be found.

antidox_xml_stylesheet

(Optional) Specify an alternative stylesheet. See Customization for instructions on how to define your own stylesheet.

Customization

antidox comes with a default template in the form of a XML stylesheet. It is possible to change the rendering of elements and even add support for other Doxygen constructs by supplying an alternate stylesheet through the antidox_xml_stylesheet parameter.

A custom stylesheet can inherit from (or include) the default one by using an import statement. A basic stylesheet can be

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="antidox:compound"/>
</xsl:stylesheet>

Currently, there is no access to the Doxygen database from within templates. This means that it is not possible to query the relationships (parent, children, etc) of the element being rendered from within the XSL template. The only information available is that which is exposed by Doxygen’s XML. That this information is available is considered by the author of this extension to be a design mistake, because it is a consequence of duplicate data all across Doxygen-generated documents. Therefore, this information is not used in the built-in templates, and it is recommended that user-supplied templates do not either. Instead, a more flexible mechanism for including the documentation of child elements is provided in the form of events- see the next section.

Events

antidox-include-default(app, this, options)

Emitted once for every c directive, to determine which child elements should be included. antidox will select the first non-None value.

Handlers should return either None, to fall back to the default behavior, or list of tuples of the form (refid, options). In the latter case, refid should be a doxy.RefId object and options a dictionary which will set the options for the nested doxy:c directive.

The default behavior is implemented by directives.default_inclusion_policy().

Parameters:
  • app – the Sphinx application object
  • this – refid for the object currently being documented.
  • options – dictionary with the options given to the directive.
antidox-include-children(app, this, options, children)

Emitted once for every c directive, after the list of children to include has been determined.

Handlers can inspect and modify the children list by adding or removing elements or changing the options. All registered handlers will be run as long as they all return None. This allows combining different filtering behaviors. Processing handlers will stop as soon as one of them returns a non-None value.

Parameters:
  • app – the Sphinx application object
  • this – refid for the object currently being documented.
  • options – dictionary with the options given to the directive.
  • children – A list of (refid, options) tuples, as returned by the antidox-include-default event.

For example, you can use this event to exclude struct members that start with and underscore:

import antidox.doxy
import antidox.directives
import re

_SINGLE_UNDERSCORE = re.compile("^_[^_].*")

def struct_no_undescore(app, this, options, children):
    """Handle the antidox-include-children event and cause it to skip struct
    members that start with a single underscore"""
    db = app.env.antidox_db

    if db.get(this)['kind'] == antidox.doxy.Kind.STRUCT:
        for el in [(k, v) for k, v in children
                    if _SINGLE_UNDERSCORE.fullmatch(db.get(k)['name'])]:
            children.remove(el)

def setup(app):
    app.connect("antidox-include-children", struct_no_undescore)
antidox-db-loaded(app, db)

Emmited after the Doxygen database is read and loaded into the environment.

Parameters:
  • app – the Sphinx application object
  • db – a antidox.doxy.DoxyDB instance.