Usage

Using exhale can be simple or involved, depending on how much you want to change and how familiar you are with things like Sphinx, Breathe, Doxygen, etc. At the top level, what you need is:

  1. Your C++ code you want to document, with “proper” Doxygen documentation. Please read the Doxygen Documentation Specifics for common documentation pitfalls, as well as features previously unavailable in standard Doxygen.

  2. A sphinx documentation project ready to go. See the Sphinx Getting Started tutorial for getting that off the ground.

Tip

Don’t know how to get started? That’s ok! There’s a lot of tools involved here, and it can be quite confusing to know what’s what. Please see the Quickstart Guide for getting started with Sphinx, Breathe, and Exhale.

Additional Usage and Customization

Controlling the Layout of the Generated Root Library Document

The main library page (at the path given by "{containmentFolder}/{rootFileName}") that you will link to from your documentation is laid out as follows:

1

{{ rootFileTitle }}

Heading

2

{{ afterTitleDescription }}

Section 1

3

Page Hierarchy

Section 2

4

Class Hierarchy

Section 3

5

File Hierarchy

Section 4

6

{{ afterHierarchyDescription }}

Section 5

7

{{ fullApiSubSectionTitle }}

Section 6

8

Unabridged API

Section 7

9

{{ afterBodySummary }}

Section 8

  1. The title of the document will be the key to "rootFileTitle" given to exhale_args in conf.py unless the \mainpage command is being used on the doxygen side. See rootFileTitle.

  2. If provided, the value of the key "afterTitleDescription" given to exhale_args will be included. See afterTitleDescription.

  3. The Page Hierarchy will be included. This section is only included if the project is using the \page / \subpage doxygen commands in its documentation. If those commands are not present, this section is not included. By default this is a bulleted list; see the Clickable Hierarchies section. The default title for this section is "Page Hierarchy", but can be changed using the key "pageHierarchySubSectionTitle" in exhale_args. See pageHierarchySubSectionTitle.

    Note

    This is performed by an .. include:: directive. The file for this section is "{containmentFolder}/page_view_hierarchy.rst.include".

    Tip

    Please also see the documentation for rootFileTitle.

  4. Next, the Class Hierarchy is included. If no class-like compounds are documented in the project (e.g., only free-standing functions), this section will not be included. By default this is a bulleted list; see the Clickable Hierarchies section.

    Note

    This is performed by an .. include:: directive. The file for this section is "{containmentFolder}/class_view_hierarchy.rst.include".

  5. Next, the File Hierarchy is included. By default this is a bulleted list; see the Clickable Hierarchies section.

    Note

    This is performed by an .. include:: directive. The file for this section is "{containmentFolder}/file_view_hierarchy.rst.include".

  6. If provided, the value of the key "afterHierarchyDescription" given to exhale_args will be included. See afterHierarchyDescription.

  7. After the Class and File Hierarchies, the unabridged API index is generated. The default title for this section is "Full API", but can be changed using the key "fullApiSubSectionTitle" in exhale_args. See fullApiSubSectionTitle.

  8. After the title or default value for (6), the full API is included. This includes links to things such as defines, functions, typedefs, etc. that are not included in the hierarchies.

    Note

    This is performed by an .. include:: directive. The file for this section is "{containmentFolder}/unabridged_api.rst.include".

    Tip

    The unabridged_api.rst performs a large number of .. toctree:: directives to link up all of the documents. You can control the number of bullets shown for each section be setting the key "fullToctreeMaxDepth" (e.g. to a smaller number such as 2). See fullToctreeMaxDepth.

    Tip

    Use unabridgedOrphanKinds to exclude entire sections from the full API listing.

  9. If provided, the value of the key "afterBodySummary" will be included at the bottom of the document. See afterBodySummary.

Tip

Where numbers (4), (5), and (8) are concerned, you should be able to happily ignore that an .. include:: is being performed. The URL for the page is strictly determined by what you specified with the required arguments "containmentFolder" and "rootFileName". However, if things are not working as expected it is useful to know where to look. The hierarchies in particular, though, may be challenging to understand if you do not know HTML (or JavaScript) and you are generating the Tree View.

Clickable Hierarchies

As stated elsewhere, the primary reason for writing Exhale is to revive the Doxygen Class and File hierarchies. The default behavior of Exhale is to simply insert bulleted lists for these. This was originally because I had hoped to support other Sphinx writers besides HTML, but that ship has pretty much sailed. Now, the reason is primarily because more information is required by the user depending on their HTML theme. Basically

  1. If you are using any theme other than the Sphinx Bootstrap Theme, simply add the argument "createTreeView": True to your exhale_args dictionary in conf.py. This will use the lightweight and surprisingly compatible collapsibleLists library for your clickable hierarchies.

  2. When using either the sphinx-bootstrap-theme, or any other theme that incorporates Bootstrap, you will need to make sure to also set "treeViewIsBootstrap": True in your exhale_args dictionary in conf.py in addition to "createTreeView": True. Exhale will then use the Bootstrap Treeview library to generate your clickable hierarchies.

    Note

    See features available on bootstrap-treeview that you want access to? Add your thoughts on the issue, explaining which feature you would want to be able to control.

    The currently available customizations begin here, but it shouldn’t be too hard to add more.

    Tip

    You will see that many of the color, selection, and search options are not available to be customized for bootstrap-treeview. This is by design. See treeViewBootstrapTextSpanClass, treeViewBootstrapIconMimicColor, and treeViewBootstrapOnhoverColor for your color options. The links are defined by your bootstrap theme’s a tag color.

See the Credit section for information on the licensing of these libraries. Neither library should produce any legal gray areas for you, but I’m not a lawyer.

Todo

add some pictures of the different hierarchies once this is packaged

Linking to a Generated File

Using the linking strategies in this section is primarily for in your website’s documentation such as index.rst or usage.rst (since those are already reStructuredText documents), or even in the supplemental arguments you supply to exhale_args such as afterTitleDescription (since these arguments get “pasted” directly onto a generated reStructuredText document).

In the actual code documentation, Breathe is typically able to infer links automatically (which is really great!), as well as you can also use \ref from Doxygen if that is not working.

Where possible, you should prefer using the Doxygen \ref command.

However, you can also use these in your code documentation provided that you enter a verbatim reStructuredText. See the Doxygen ALIASES section for more information on that.

Suggested reStructuredText Linking Strategy

Assuming you have set primary_domain = 'cpp' (as shown in the Quickstart Guide), you should be able to use the linking strategies provided by Sphinx itself without needing to prefix everything with cpp:. Some examples:

Action

Syntax

Linking to a class

:class:`namespace::ClassName`

Linking to a method of a class

:func:`namespace::ClassName::methodName`

Linking to a member of a class

:member:`namespace::ClassName::mMemberName`

Linking to a function

:func:`namespace::funcName`

Tip

The value of primary_domain in conf.py is very important here! If you do not set it, the default is py (python). This means that instead of :class:`namespace::ClassName` you would need to use :cpp:class:`namespace::ClassName` to use a different domain.

A much more thorough walk-through of how the different domains can be used together (e.g., how to link to a define or macro) is provided in the companion website’s Using Intersphinx guide.

Page Level Customization

Each page generated for a given “leaf-like” node (classes, structs, functions) will look something like this, where special treatment is given to File pages specifically:

{{ pageLevelConfigMeta }}

Meta

{{ Node Title }}

Heading

1

Definition {{ link to file or program listing }}

Section 1

2

{{ contentsDirectives }}

{{ Kind Specific Exhale Links }}

Section 2

{{ Breathe Directive }}

Section 3
Meta

The page-level metadata is controlled by pageLevelConfigMeta. It is only included if provided.

Heading

The internal reStructuredText link and page heading are included. These are determined by the ExhaleNode object’s link_name and title members, respectively.

Section 1
File Pages

  1. If using Exhale to generate Doxygen on STDIN, the XML_PROGRAMLISTING Doxygen variable is set to YES, and an associated program listing page is generated for each file and linked to here.

    Tip

    The value of doxygenStripFromPath directly affects what path is displayed here.

    Danger

    If you override XML_PROGRAMLISTING = NO (or do not explicitly set it to YES if using alternative Doxygen generation methods), significantly more than just whether or not the program listing document is generated is affected. There are numerous graph relationships that Exhale cannot recover without the xml program listing.

  2. See the Using Contents Directives section.

For File pages, the brief description of the File (if provided) is included in Section 1 underneath the title. See File and Namespace Level Documentation in Exhale

Other Pages

  1. Assuming Exhale was able to infer which file defined a given node, a link to the file page that defined it is included here.

  2. See the Using Contents Directives section.

For Namespace pages, the brief description of the Namespace (if provided) is included in Section 1 underneath the title. See File and Namespace Level Documentation in Exhale.

Section 2
File Pages

At the beginning of section 2, the detailed description of the file is included if provided.

Afterward, an enumeration of the files that this file #include s, as well as files that #include this file, is presented next. Afterward, an enumeration by kind (namespaces, classes, functions, etc) that were defined in this file are included.

Other Pages

For many pages, section 2 will be blank.

Classes and Structs

Links to any nested classes (of this type, or the containing class if this is a nested type) are included. Afterward, links to any base or derived classes are included.

If includeTemplateParamOrderList is True, the template parameter list enumeration is included next.

Namespaces

Namespaces will include an enumeration of everything that was determined to be a member of this namespace, listed by kind. So things like nested namespaces, classes and structs, functions, etc.

Section 3
File Pages

If Exhale is producing unexpected output for file level documentation, you can set generateBreatheFileDirectives to True as a debugging feature.

Please refer to the Doxygen Documentation Specifics section for potential causes, in particular the subsection describing File and Namespace Level Documentation in Exhale.

Namespaces

No Breathe directives for namespaces are used, as they will cause the same problems that the file directives do.

Please refer to the File and Namespace Level Documentation in Exhale section.

Other Pages

For all other pages (except for directories, which simply link to subdirectories and files in that directory), this is where the Breathe directive is inserted.

Tip

See the Customizing Breathe Output section for how you can modify this section of a given document.

Using Contents Directives

Note

I put a lot of thought into the defaults for the .. contents:: directive. I believe the chosen defaults are optimal, but this is very much a personal decision. It also depends a lot on what html_theme you are using in conf.py. For example, the sphinx_rtd_theme (while classy) leaves a lot to the imagination where page-level navigation is concerned (and the page is long).

The Contents Directive can be used to display the table of contents on an individual reStructuredText page. This is different than the toctree directive in that it is not specifying a list of documents to include next, it is simply informing the reStructuredText parser (Sphinx in our case) that you would like a table of contents displayed where this directive appears.

By default, Exhale includes a .. contents:: directive on all File and Namespace pages. This is particularly useful for making the Namespace and File pages navigable by the reader of your documentation when the Namespace / File incorporates many parts of the API. Classes and structs have potential for a contents directive to be warranted (e.g., complex inheritance relationships with nested types, core base types that every class in the API inherits from). If you have particular Classes or Structs that warrant a .. contents:: directive, you can enable this. However, at this time, this is a global setting for Exhale — either all have it or none have it. That said, the presence of a .. contents:: directive on simple class / struct pages doesn’t seem to be too distracting.

On the other hand, pages generated for things like Directories, Enums, Variables, Defines, Typedefs, etc, are generally only as long as the documentation so they do not receive a .. contents:: directive by default.

The way Exhale is setup is to coordinate four variables:

  1. contentsDirectives sets globally whether or not any .. contents:: directives are generated.

  2. contentsTitle determines the title of these directives. The default is the reStructuredText default: Contents.

  3. contentsSpecifiers provides the specifications to apply to the .. contents:: directives. For stylistic reasons, the specifiers Exhale defaults to are :local: and :backlinks: none.

  4. kindsWithContentsDirectives specifies the kinds of compounds that will include a .. contents:: directive. The default is to only generate these for namespace and file.

The implementation, if interested, is in contentsDirectiveOrNone(). Assuming you use all of the Exhale defaults, then every Namespace and File document will include a directive like this:

.. contents:: Contents
   :local:
   :backlinks: none

These defaults basically have two implications:

The Effect of :local: on the Title

The :local: option states to only include the table of contents for the remainder of the page. For Exhale, this means do not include the title of the page.

When using :local:, the title must be explicitly specified. So if you set contentsTitle to the empty string (keeping all other defaults), the directive generated would be

.. contents::
   :local:
   :backlinks: none

which results in a table of contents, without the word Contents before it. This is likely a personal preference.

The Effect of :backlinks:

Traditional usage of a .. contents:: directive, when :backlinks: is not explicitly specified, is to create circular links. When considering writing a long document with many sections and subsections, this is exceptionally convenient.

This means that when you click on a link in the generated table of contents, it takes you to the heading for that section. The heading is also a hyperlink, which when clicked takes you back to the table of contents.

I find this to be awkward for Exhale for two reasons:

  1. Section titles as hyperlinks, especially with Bootstrap, are quite unattractive.

  2. The circular linking is not exactly intuitive for code documentation.

Alas these are things that very much depend on your personal preferences, so I’ve done my best to enable as much flexibility as possible.

Customizing Breathe Output

The directives for generating the documentation for a given node come from Breathe. Exhale uses the Breathe defaults for all directives, except for Classes and Structs. Suppose you are documenting a class namespace::ClassName. Exhale will produce the following directive:

.. doxygenclass:: namespace::ClassName
   :members:
   :protected-members:
   :undoc-members:

where the defaults being overridden are to include :protected-members: as well as :undoc-members:. You may, for example, want to also include :private-members: in your documentation, or override the default settings for other Breathe directives to control what is displayed.

In order to override these settings, a layer of indirection has to be added. Because Exhale is a Sphinx Extension, it needs to be possible to do something called “Pickle”. The short version of what this means is that you cannot give me a function directly to call, because the Python function object cannot be pickled. The solution is to use the wrapper function I have created that takes your input function and stores all possible inputs and outputs in a dictionary. Details aside, it’s easier than it sounds.

  1. Define your custom specifications function in conf.py. In this example we’ll be changing the specifications for the class, struct, and enum directives, and use the Breathe defaults for everything else:

    # somewhere in `conf.py`, *BEFORE* declaring `exhale_args`
def specificationsForKind(kind):
    '''
    For a given input ``kind``, return the list of reStructuredText specifications
    for the associated Breathe directive.
    '''
    # Change the defaults for .. doxygenclass:: and .. doxygenstruct::
    if kind == "class" or kind == "struct":
        return [
          ":members:",
          ":protected-members:",
          ":private-members:",
          ":undoc-members:"
        ]
    # Change the defaults for .. doxygenenum::
    elif kind == "enum":
        return [":no-link:"]
    # An empty list signals to Exhale to use the defaults
    else:
        return []

    Tip

    The full list of inputs your function will be called with are defined by AVAILABLE_KINDS.

  2. Use Exhale’s utility function to create the correct dictionary. Below that function you can now do

    # Use exhale's utility function to transform `specificationsForKind`
# defined above into something Exhale can use
from exhale import utils
exhale_args = {
    # ... required arguments / other configs ...
    "customSpecificationsMapping": utils.makeCustomSpecificationsMapping(
        specificationsForKind
    )
}

    Note

    The parameter to makeCustomSpecificationsMapping() is the function itself.

Fully Automated Building

It is preferable to have everything generated at once, e.g. if you wish to host your documentation on Read the Docs. Exhale is configured to enable this directly for you, provided that you have the associated configuration variables setup.

Using Exhale to Execute Doxygen

To have Exhale launch Doxygen when you run make html, you will need to set exhaleExecutesDoxygen to True. After setting that, you will need to choose how Exhale is executing Doxygen. If you already know what you are doing, continue on. If you’ve never used Doxygen before, skim this, but refer to the Mastering Doxygen for more information on areas that you may get confused by.

Suggested Approach

Provide a (multiline) string to exhaleDoxygenStdin. In the Quickstart Guide, the bare minimum needed to get things off the ground was used: INPUT must be set to tell Doxygen where to look.

Tip

If you set verboseBuild to True, Exhale will print out exactly what it sends to Doxygen.

Presumably just specifying INPUT will not be enough, particularly if the Doxygen preprocessor is not understanding your code. Exhale uses a number of defaults to send to Doxygen as specified by DEFAULT_DOXYGEN_STDIN_BASE. The way these are used with your argument are as follows:

# doxy_dir is the parent directory of what you specified in
# `breathe_projects[breathe_default_project]` in `conf.py`
internal_configs = textwrap.dedent('''
    # Tell doxygen to output wherever breathe is expecting things
    OUTPUT_DIRECTORY       = {out}
    # Tell doxygen to strip the path names (RTD builds produce long abs paths...)
    STRIP_FROM_PATH        = {strip}
'''.format(out=doxy_dir, strip=configs.doxygenStripFromPath))

# The configurations you specified
external_configs = textwrap.dedent(configs.exhaleDoxygenStdin)

# The full input being sent
full_input = "{base}\n{external}\n{internal}\n\n".format(
    base=configs.DEFAULT_DOXYGEN_STDIN_BASE,
    external=external_configs,
    internal=internal_configs
)

In words, first the Exhale defaults are sent in. Then your configurations, allowing you to override anything you need. Last, the output directory and strip from path (specified elsewhere) are sent in.

The error checking and warning logic seems pretty robust. For example, suppose you need to add to the PREDEFINED to add a definition. If you did something like

import textwrap
exhale_args = {
    # ... required args ...
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin": textwrap.dedent('''
        INPUT      = ../include
        # Using `=` instead of `+=` overrides
        PREDEFINED = FOO="12"
    ''')
}

This will override the PREDEFINED section in the default configurations. Exhale will produce a warning encouraging you to +=, but still continue.

Using a Doxyfile

If you have your own customized Doxyfile, just make sure it is in the same directory as conf.py. See the documentation for exhaleUseDoxyfile for items you need to make sure agree with the configurations you have applied elsewhere to Breathe / Exhale.

Executing Doxygen Independently

This is another option, just make sure that Doxygen is run before Exhale is. See the note at the bottom of the Quickstart Guide.

Doxygen Documentation Specifics

To have Exhale launch Doxygen when you run make html, you will need to set exhaleExecutesDoxygen to True. After setting that, you will need to choose how Exhale is executing Doxygen. If you already know what you are doing, continue on. If you’ve never used Doxygen before, skim this, but refer to the Mastering Doxygen for more information on areas that you may get confused by.

Suggested Approach

Provide a (multiline) string to exhaleDoxygenStdin. In the Quickstart Guide, the bare minimum needed to get things off the ground was used: INPUT must be set to tell Doxygen where to look.

Tip

If you set verboseBuild to True, Exhale will print out exactly what it sends to Doxygen.

Presumably just specifying INPUT will not be enough, particularly if the Doxygen preprocessor is not understanding your code. Exhale uses a number of defaults to send to Doxygen as specified by DEFAULT_DOXYGEN_STDIN_BASE. The way these are used with your argument are as follows:

# doxy_dir is the parent directory of what you specified in
# `breathe_projects[breathe_default_project]` in `conf.py`
internal_configs = textwrap.dedent('''
    # Tell doxygen to output wherever breathe is expecting things
    OUTPUT_DIRECTORY       = {out}
    # Tell doxygen to strip the path names (RTD builds produce long abs paths...)
    STRIP_FROM_PATH        = {strip}
'''.format(out=doxy_dir, strip=configs.doxygenStripFromPath))

# The configurations you specified
external_configs = textwrap.dedent(configs.exhaleDoxygenStdin)

# The full input being sent
full_input = "{base}\n{external}\n{internal}\n\n".format(
    base=configs.DEFAULT_DOXYGEN_STDIN_BASE,
    external=external_configs,
    internal=internal_configs
)

In words, first the Exhale defaults are sent in. Then your configurations, allowing you to override anything you need. Last, the output directory and strip from path (specified elsewhere) are sent in.

The error checking and warning logic seems pretty robust. For example, suppose you need to add to the PREDEFINED to add a definition. If you did something like

import textwrap
exhale_args = {
    # ... required args ...
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin": textwrap.dedent('''
        INPUT      = ../include
        # Using `=` instead of `+=` overrides
        PREDEFINED = FOO="12"
    ''')
}

This will override the PREDEFINED section in the default configurations. Exhale will produce a warning encouraging you to +=, but still continue.

Using a Doxyfile

If you have your own customized Doxyfile, just make sure it is in the same directory as conf.py. See the documentation for exhaleUseDoxyfile for items you need to make sure agree with the configurations you have applied elsewhere to Breathe / Exhale.

File and Namespace Level Documentation in Exhale

Since the Breathe file / namespace directives cannot be used, Exhale implements a “best-faith-effort” documentation parser. It includes support for a few basic block-level elements such as listings, but it is definitively not robust. If the file or namespace level documentation is rendering in unexpected ways, this is because your documentation is “too advanced” for Exhale’s mini-parser.

Tip

See the walk() method for the currently supported Doxygen formatting being parsed.

However, the solution is easy: use a verbatim reStructuredText environment in the documentation. See how to do that in the Doxygen ALIASES section.

Note

By entering a verbatim RST environment, doxygen commands such as \ref are no longer available. Or rather, they will be parsed as-is without actually generating a link to the desired target. Since you’ve now entered a verbatim RST environment, you would instead use the Sphinx domain links.

So if you were linking to class namespace::ClassName using \ref namespace::ClassName, this would now change to be :class:`namespace::ClassName`. See the Sphinx Cross Referencing Guide for some more examples. There is also an Intersphinx Guide available on the companion website with some examples of linking to macros.