Developer Reference Documentation¶

Primary Entry Point¶

The main entry point to exhale is through the generate function. This method internally calls breathe, reparses / rebuilds the hierarchies, and then generates the API.

exhale.generate(exhaleArgs)¶

The main entry point to exhale, which parses and generates the full API.

Parameters:	`exhaleArgs` (dict) The dictionary of arguments to configure exhale with. All keys are strings, and most values should also be strings. See below.

Required Entries:

key: "doxygenIndexXMLPath" — value type: str

The absolute or relative path to where the Doxygen index.xml is. A relative path must be relative to the file calling exhale.

key: "containmentFolder" — value type: str

The folder the generated API will be created in. If the folder does not exist, exhale will create the folder. The path can be absolute, or relative to the file that is calling exhale. For example, "./generated_api".

key: "rootFileName" — value type: str

The name of the file that you will be linking to from your reStructuredText documents. Do not include the containmentFolder path in this file name, exhale will create the file "{}/{}".format(containmentFolder, rootFileName).

In order for Sphinx to be happy, you should include a .rst suffix. All of the generated API uses reStructuredText, and that will not ever change.

For example, if you specify

"containmentFolder" = "./generated_api", and
"rootFileName" = "library_root.rst"

Then exhale will generate the file ./generated_api/library_root.rst.

You could include this file in a toctree directive (say in index.rst) with:

.. toctree:
   :maxdepth: 2

   generated_api/library_root

Since Sphinx allows for some flexibility (e.g. your primary domain may be using .txt files), no error checking will be performed.

key: "rootFileTitle" — value type: str

The title to be written at the top of rootFileName, which will appear in your file including it in the toctree directive.

key: "doxygenStripFromPath" — value type: str

When building on Read the Docs, there seem to be issues regarding the Doxygen variable STRIP_FROM_PATH when built remotely. That is, it isn’t stripped at all. Provide me with a string path (e.g. ".."), and I will strip this for you for the File nodes being generated. I will use the exact value of os.path.abspath("..") in the example above, so you can supply either a relative or absolute path. The File view hierarchy will break if you do not give me a value for this, and therefore I hesitantly require this argument. The value ".." assumes that conf.py is in a docs/ or similar folder exactly one level below the repository’s root.

Additional Options:

key: "afterTitleDescription" — value type: str

Properly formatted reStructuredText with no indentation to be included directly after the title. You can use any rst directives or formatting you wish in this string. I suggest using the textwrap module, e.g.:

description = textwrap.dedent('''
This is a description of the functionality of the library being documented.

.. warning::

   Please be advised that this library does not do anything.
''')

Then you can add "afterTitleDescription" = description to your dictionary.

key: "afterBodySummary" — value type: str

Similar to afterTitleDescription, this is a string with reStructuredText formatting. This will be inserted after the generated API body. The layout looks something like this:

rootFileTitle
============================================================================

afterTitleDescription (if provided)

[[[ GENERATED API BODY ]]]

afterBodySummary (if provided)

key: "createTreeView" — value type: bool

For portability, the default value if not specified is False, which will generate reStructuredText bulleted lists for the Class View and File View hierarchies. If True, raw html unordered lists will be generated. Please refer to the Clickable Hierarchies subsection of Additional Usage and Customization for more details.

key: "fullToctreeMaxDepth" — value type: int

Beneath the Class View and File View hierarchies a Full API listing is generated as there are items that may not appear in the Class View hierarchy, as well as without this an obscene amount of warnings are generated from Sphinx because neither view actually uses a toctree, they link directly.

The default value is 5 if not specified, but you may want to give a smaller value depending on the framework being documented. This value must be greater than or equal to 1 (this is the value of :maxdepth:).

key: "appendBreatheFileDirective" — value type: bool

Currently, I do not know how to reliably extract the brief / detailed file descriptions for a given file node. Therefore, if you have file level documentation in your project that has meaning, it would otherwise be omitted. As a temporary patch, if you specify this value as True then at the bottom of the file page the full doxygenfile directive output from Breathe will be appended to the file documentiation. File level brief and detailed descriptions will be included, followed by a large amount of duplication. I hope to remove this value soon, in place of either parsing the xml more carefully or finding out how to extract this information directly from Breathe.

The default value of this behavior is False if it is not specified in the dictionary passed as input for this method. Please refer to the Customizing File Pages subsection of Customizing File Pages for more information on what the impact of this variable is.

key: "customSpecificationFunction" — value type: function

The custom specification function to override the default behavior of exhale. Please refer to the exhale.specificationsForKind() documentation.

Raises:	ValueError – If the required dictionary arguments are not present, or any of the (key, value) pairs are invalid. RuntimeError – If any fatal error is caught during the generation of the API.

Helper Functions¶

There are a few helper functions used throughout the framework that effectively just reformat the input into a specific kind of output for incorporating into reStructuredText documents, and the directives used in those documents. The last function is largely unrelated to exhale, and just prints something to the console in a way that makes it stick out a little more.

exhale.qualifyKind(kind)¶

Qualifies the breathe kind and returns an qualifier string describing this to be used for the text output (e.g. in generated file headings and link names).

The output for a given kind is as follows:

Input Kind	Output Qualifier
“class”	“Class”
“define”	“Define”
“enum”	“Enum”
“enumvalue”	“Enumvalue”
“file”	“File”
“function”	“Function”
“group”	“Group”
“namespace”	“Namespace”
“struct”	“Struct”
“typedef”	“Typedef”
“union”	“Union”
“variable”	“Variable”

The following breathe kinds are ignored:

“autodoxygenfile”
“doxygenindex”
“autodoxygenindex”

Note also that although a return value is generated, neither “enumvalue” nor “group” are actually used.

Parameters:	`kind` (str) The return value of a Breathe `compound` object’s `get_kind()` method.
Return (str):	The qualifying string that will be used to build the reStructuredText titles and other qualifying names. If the empty string is returned then it was not recognized.

exhale.kindAsBreatheDirective(kind)¶

Returns the appropriate breathe restructured text directive for the specified kind. The output for a given kind is as follows:

Input Kind	Output Directive
“class”	“doxygenclass”
“define”	“doxygendefine”
“enum”	“doxygenenum”
“enumvalue”	“doxygenenumvalue”
“file”	“doxygenfile”
“function”	“doxygenfunction”
“group”	“doxygengroup”
“namespace”	“doxygennamespace”
“struct”	“doxygenstruct”
“typedef”	“doxygentypedef”
“union”	“doxygenunion”
“variable”	“doxygenvariable”

The following breathe kinds are ignored:

“autodoxygenfile”
“doxygenindex”
“autodoxygenindex”

Note also that although a return value is generated, neither “enumvalue” nor “group” are actually used.

Parameters:	`kind` (str) The kind of the breathe compound / ExhaleNode object (same values).
Return (str):	The directive to be used for the given `kind`. The empty string is returned for both unrecognized and ignored input values.

exhale.specificationsForKind(kind)¶

Returns the relevant modifiers for the restructured text directive associated with the input kind. The only considered values for the default implementation are class and struct, for which the return value is exactly:

"   :members:\n   :protected-members:\n   :undoc-members:\n"

Formatting of the return is fundamentally important, it must include both the prior indentation as well as newlines separating any relevant directive modifiers. The way the framework uses this function is very specific; if you do not follow the conventions then sphinx will explode.

Consider a struct thing being documented. The file generated for this will be:

.. _struct_thing:

Struct thing
================================================================================

.. doxygenstruct:: thing
   :members:
   :protected-members:
   :undoc-members:

Assuming the first two lines will be in a variable called link_declaration, and the next three lines are stored in header, the following is performed:

directive = ".. {}:: {}\n".format(kindAsBreatheDirective(node.kind), node.name)
specifications = "{}\n\n".format(specificationsForKind(node.kind))
gen_file.write("{}{}{}{}".format(link_declaration, header, directive, specifications))

That is, no preceding newline should be returned from your custom function, and no trailing newline is needed. Your indentation for each specifier should be exactly three spaces, and if you want more than one you need a newline in between every specification you want to include. Whitespace control is handled internally because many of the directives do not need anything added. For a full listing of what your specifier options are, refer to the breathe documentation:

http://breathe.readthedocs.io/en/latest/directives.html

Parameters:	`kind` (str) The kind of the node we are generating the directive specifications for.
Return (str):	The correctly formatted specifier(s) for the given `kind`. If no specifier(s) are necessary or desired, the empty string is returned.

exhale.exclaimError(msg, ansi_fmt='34;1m')¶

Prints msg to the console in color with (!) prepended in color.

Example (uncolorized) output of exclaimError("No leading space needed."):

(!) No leading space needed.

All messages are written to sys.stderr, and are closed with [0m. The default color is blue, but can be changed using ansi_fmt.

Documentation building has a verbose output process, this just helps distinguish an error message coming from exhale.

Parameters:	`msg` (str) The message you want printed to standard error. `ansi_fmt` (str) An ansi color format. `msg` is printed as `"\033[" + ansi_fmt + msg + "\033[0m\n`, so you should specify both the color code and the format code (after the semicolon). The default value is `34;1m` — refer to http://misc.flogisoft.com/bash/tip_colors_and_formatting for alternatives.

Exposed Utility Variables¶

exhale.EXHALE_FILE_HEADING¶: The restructured text file heading separator ("=" * 88).

exhale.EXHALE_SECTION_HEADING¶: The restructured text section heading separator ("-" * 88).

exhale.EXHALE_SUBSECTION_HEADING¶: The restructured text sub-section heading separator ("*" * 88).

Ownership Graph Representation¶

A graph representing what classes belong to what namespaces, what file defines what, etc is built with a single ExhaleRoot. This root node contains multiple different lists of ExhaleNode objects that it parses from both Breathe and the Doxygen xml output.

If you are reading this, then you are likely trying to make changes. To avoid having such a huge reference page, and enable viewing the reference documentation for the two primary classes at the same time, they are on separate pages.