Contents
exhale.configs
Both Breathe and Exhale require that you already have Doxygen xml
documentation generated before they are launched. See the usage_fully_automated
section for more information.
There are 6 required arguments you must provide in your conf.py
. 2 are for Breathe, and 4 are for Exhale.
Breathe is setup to allow for multiple projects being controlled by a single conf.py
to rule them all. Exhale only supports generating one "project" API at a time. The project that Exhale will generate is determined by what you signal to Breathe as your default project. The two arguments that must be present in your conf.py
for Breathe are as follows:
- Mapping of Project Names to Doxygen XML Output Paths
breathe_projects
(dict)- Keys: strings that are the name of a given project.
- Values: strings that are (absolute or relative) paths to where the Doxygen XML output has been generated.
So if the Doxygen documentation was generated to the path
./_doxygen/xml
, and your project was called"My Project"
, you would include the following in yourconf.py
:breathe_projects = { "My Project": "./_doxygen/xml" }
Tip
When specifying relative paths, they are all relative to
conf.py
.
- Selecting the Project to Generate
breathe_default_project
(str)Since Breathe can support multiple projects, specify the default project so that Exhale will know which one to use (when more than one project is available).
Following from the example above, where the key in
breathe_projects
we want to generate is"My Project"
, you would include the following you yourconf.py
:breathe_default_project = "My Project"
Users must provide the following values to exhale_args
in their conf.py
.
Tip
Recall the variable name conventions from above. If you want to specify the value for containmentFolder
so that ~exhale.configs.containmentFolder
is populated, the name of the key is the string "containmentFolder"
. Each entry below details what the type
of the value of the key should be. So in this case you might have
exhale_args = {
"containmentFolder": "./api",
# other required entries here
}
exhale.configs.containmentFolder
exhale.configs.rootFileName
exhale.configs.doxygenStripFromPath
exhale.configs.rootFileTitle
exhale.configs.verboseBuild
exhale.configs.alwaysColorize
exhale.configs.generateBreatheFileDirectives
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
- The title of the document will be the key to
"rootFileTitle"
given toexhale_args
inconf.py
unless the\mainpage
command is being used on the doxygen side. See~exhale.configs.rootFileTitle
. - If provided, the value of the key
"afterTitleDescription"
given toexhale_args
will be included. See~exhale.configs.afterTitleDescription
. 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 theusage_creating_the_treeview
section. The default title for this section is"Page Hierarchy"
, but can be changed using the key"pageHierarchySubSectionTitle"
inexhale_args
. See~exhale.configs.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
~exhale.configs.rootFileTitle
.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
usage_creating_the_treeview
section.Note
This is performed by an
.. include::
directive. The file for this section is"{containmentFolder}/class_view_hierarchy.rst.include"
.Next, the File Hierarchy is included. By default this is a bulleted list; see the
usage_creating_the_treeview
section.Note
This is performed by an
.. include::
directive. The file for this section is"{containmentFolder}/file_view_hierarchy.rst.include"
.- If provided, the value of the key
"afterHierarchyDescription"
given toexhale_args
will be included. See~exhale.configs.afterHierarchyDescription
. - 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"
inexhale_args
. See~exhale.configs.fullApiSubSectionTitle
. 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 as2
). See~exhale.configs.fullToctreeMaxDepth
.Tip
Use
~exhale.configs.unabridgedOrphanKinds
to exclude entire sections from the full API listing.- If provided, the value of the key
"afterBodySummary"
will be included at the bottom of the document. See~exhale.configs.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.
exhale.configs.afterTitleDescription
exhale.configs.pageHierarchySubSectionTitle
exhale.configs.afterHierarchyDescription
exhale.configs.fullApiSubSectionTitle
exhale.configs.afterBodySummary
exhale.configs.fullToctreeMaxDepth
exhale.configs.listingExclude
exhale.configs.unabridgedOrphanKinds
To compose the different sections of the root document, exhale generates some additional files to .. include::
them. Depending on the compounds documented in doxygen as well as other settings different entries in the example below may or may not be generated.
=======================
Some Title You Provided
=======================
.. include:: page_index.rst.include
.. include:: page_view_hierarchy.rst.include
.. include:: class_view_hierarchy.rst.include
.. include:: file_view_hierarchy.rst.include
.. include:: unabridged_api.rst.include
These should not use a file extension found in sphinx:source_suffix
, since the file class_view_hierarchy.rst
for example will also be processed into html. This results in warnings between duplicate labels being found in both the root document and the document being included (more information here).
To manually index through the generated exhale documents, you can set ~exhale.configs.rootFileName
to "EXCLUDE"
. With the root file out of the picture, you may seek to .. include::
(or add to a .. toctree::
) one of the documents above. In the .. toctree::
scenario, you will want the file extension to be .rst
so that sphinx will process it.
exhale.configs.classHierarchyFilename
exhale.configs.fileHierarchyFilename
exhale.configs.pageHierarchyFilename
exhale.configs.unabridgedApiFilename
exhale.configs.unabridgedOrphanFilename
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
If you are using any theme other than the Sphinx Bootstrap Theme, simply add the argument
"createTreeView": True
to yourexhale_args
dictionary inconf.py
. This will use the lightweight and surprisingly compatible collapsibleLists library for your clickable hierarchies.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 yourexhale_args
dictionary inconf.py
in addition to"createTreeView": True
. Exhale will then use the Bootstrap Treeview library to generate your clickable hierarchies.__ https://github.com/jonmiles/bootstrap-treeview
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 <bootstrap_mods>
, 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~exhale.configs.treeViewBootstrapTextSpanClass
,~exhale.configs.treeViewBootstrapIconMimicColor
, and~exhale.configs.treeViewBootstrapOnhoverColor
for your color options. The links are defined by your bootstrap theme'sa
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.
add some pictures of the different hierarchies once this is packaged
exhale.configs.createTreeView
exhale.configs.minifyTreeView
exhale.configs.treeViewIsBootstrap
exhale.configs.treeViewBootstrapTextSpanClass
exhale.configs.treeViewBootstrapIconMimicColor
exhale.configs.treeViewBootstrapOnhoverColor
exhale.configs.treeViewBootstrapUseBadgeTags
exhale.configs.treeViewBootstrapExpandIcon
exhale.configs.treeViewBootstrapCollapseIcon
exhale.configs.treeViewBootstrapLevels
exhale.configs._class_hierarchy_id
exhale.configs._file_hierarchy_id
exhale.configs._page_hierarchy_id
exhale.configs._bstrap_class_hierarchy_fn_data_name
exhale.configs._bstrap_file_hierarchy_fn_data_name
exhale.configs._bstrap_page_hierarchy_fn_data_name
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
~exhale.configs.pageLevelConfigMeta
. It is only included if provided.- Heading
The internal reStructuredText link and page heading are included. These are determined by the
~exhale.graph.ExhaleNode
object'slink_name
andtitle
members, respectively.- Section 1
- File Pages
If using Exhale to generate Doxygen on STDIN, the
XML_PROGRAMLISTING
Doxygen variable is set toYES
, and an associated program listing page is generated for each file and linked to here.Tip
The value of
~exhale.configs.doxygenStripFromPath
directly affects what path is displayed here.Danger
If you override
XML_PROGRAMLISTING = NO
(or do not explicitly set it toYES
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.- 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. Seefile_and_namespace_level_documentation_in_exhale
- Other Pages
- Assuming Exhale was able to infer which file defined a given node, a link to the file page that defined it is included here.
- 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. Seefile_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
~exhale.configs.includeTemplateParamOrderList
isTrue
, 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
~exhale.configs.generateBreatheFileDirectives
toTrue
as a debugging feature.Please refer to the
doxygen_documentation_specifics
section for potential causes, in particular the subsection describingfile_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
usage_customizing_breathe_output
section for how you can modify this section of a given document.
exhale.configs.includeTemplateParamOrderList
exhale.configs.pageLevelConfigMeta
exhale.configs.repoRedirectURL
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:
~exhale.configs.contentsDirectives
sets globally whether or not any.. contents::
directives are generated.~exhale.configs.contentsTitle
determines the title of these directives. The default is the reStructuredText default:Contents
.~exhale.configs.contentsSpecifiers
provides the specifications to apply to the.. contents::
directives. For stylistic reasons, the specifiers Exhale defaults to are:local:
and:backlinks: none
.~exhale.configs.kindsWithContentsDirectives
specifies the kinds of compounds that will include a.. contents::
directive. The default is to only generate these fornamespace
andfile
.
The implementation, if interested, is in ~exhale.utils.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~exhale.configs.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:
- Section titles as hyperlinks, especially with Bootstrap, are quite unattractive.
- 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.
exhale.configs.contentsDirectives
exhale.configs.contentsTitle
exhale.configs.contentsSpecifiers
exhale.configs.kindsWithContentsDirectives
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.
Define your custom specifications function in
conf.py
. In this example we'll be changing the specifications for theclass
,struct
, andenum
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
~exhale.utils.AVAILABLE_KINDS
.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
~exhale.utils.makeCustomSpecificationsMapping
is the function itself.
exhale.configs.customSpecificationsMapping
exhale.configs._closure_map_sanity_check
To have Exhale launch Doxygen when you run make html
, you will need to set ~exhale.configs.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 <mastering_doxygen>
for more information on areas that you may get confused by.
- Suggested Approach
Provide a (multiline) string to
~exhale.configs.exhaleDoxygenStdin
. In thequickstart_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
~exhale.configs.verboseBuild
toTrue
, 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~exhale.configs.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 likeimport 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 asconf.py
. See the documentation for~exhale.configs.exhaleUseDoxyfile
for items you need to make sure agree with the configurations you have applied elsewhere to Breathe / Exhale.
exhale.configs._doxygen_xml_output_directory
exhale.configs.exhaleExecutesDoxygen
exhale.configs.exhaleUseDoxyfile
exhale.configs.exhaleDoxygenStdin
exhale.configs.DEFAULT_DOXYGEN_STDIN_BASE
exhale.configs.exhaleSilentDoxygen
exhale.configs.lexerMapping
exhale.configs._compiled_lexer_mapping
exhale.configs.SECTION_HEADING_CHAR
exhale.configs.SUB_SECTION_HEADING_CHAR
exhale.configs.SUB_SUB_SECTION_HEADING_CHAR
exhale.configs.MAXIMUM_FILENAME_LENGTH
exhale.configs.MAXIMUM_WINDOWS_PATH_LENGTH
exhale.configs._the_app
exhale.configs._app_src_dir
exhale.configs._on_rtd
exhale.configs.apply_sphinx_configurations