Exhale Configs Module¶
Contents
The configs
module exists to contain the Sphinx Application configurations specific
to this extension. Almost every global
variable defined in this file can be
modified using the exhale_args
in conf.py
. The convention for this file is as
follows:
Things that are not supposed to change, because their value is expected to be constant, are declared in
ALL_CAPS
. SeeInternal / private variables that are not supposed to changed except for by this extension are declared as
_lower_case_with_single_leading_underscore
as is common in Python ;).Every other variable is declared as
camelCase
, indicating that it can be configured indirectly by using it as a key in the arguments toexhale_args
present in yourconf.py
. For example, one of the required arguments for this extension iscontainmentFolder
. This means that the key"containmentFolder"
is expected to be present inexhale_args
.exhale_args = { "containmentFolder": "./api", # ... }
Read the documentation for the various configs present to see what the various options are to modify the behavior of Exhale.
Required Configuration Arguments¶
Both Breathe and Exhale require that you already have Doxygen xml
documentation
generated before they are launched. See the Fully Automated Building 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.
Required Arguments for Breathe¶
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
./doxyoutput/xml
, and your project was called"My Project"
, you would include the following in yourconf.py
:breathe_projects = { "My Project": "./doxyoutput/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"
Required Arguments for Exhale¶
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 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
= None¶ - Required
The location where Exhale is going to generate all of the reStructuredText documents.
- Value in
exhale_args
(str) The value of key
"containmentFolder"
should be a string representing the (relative or absolute) path to the location where Exhale will be creating all of the files. Relative paths are relative to the Sphinx application source directory, which is almost always wherever the fileconf.py
is.Note
To better help you the user know what Exhale is generating (and therefore safe to delete), it is a hard requirement that
containmentFolder
is a subdirectory of the Sphinx Source Directory. AKA the path"."
will be rejected, but the path"./api"
will be accepted.The suggested value for
"containmentFolder"
is"./api"
, or"./source/api"
if you have separate source and build directories with Sphinx. When the html is eventually generated, this will make for a more human friendly url being generated.Warning
The verbiage subdirectory means direct subdirectory. So the path
"./library/api"
will be rejected. This is because I make the assumption thatcontainmentFolder
is “owned” by Exhale / is safe to delete.
-
exhale.configs.
rootFileName
= None¶ - Required
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"{contaimentFolder}/{rootFileName}"
for you.- Value in
exhale_args
(str) The value of key
"rootFileName"
should be a string representing the name of the file you will be including in your top-leveltoctree
directive. 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" = "./api"
, and"rootFileName" = "library_root.rst"
Then exhale will generate the file
./api/library_root.rst
. You would then include this file in atoctree
directive (say inindex.rst
) with:.. toctree:: :maxdepth: 2 about api/library_root
-
exhale.configs.
rootFileTitle
= None¶ - Required
The title to be written at the top of
rootFileName
, which will appear in your file including it in thetoctree
directive.- Value in
exhale_args
(str) The value of the key
"rootFileTitle"
should be a string that has the title of the main library root document folder Exhale will be generating. The user is required to supply this value because its value directly affects the overall presentation of your documentation. For example, if you are including the Exhale generated library root file in yourindex.rst
top-leveltoctree
directive, the title you supply here will show up on both your main page, as well as in the navigation menus.An example value could be
"Library API"
.
-
exhale.configs.
doxygenStripFromPath
= None¶ - Required
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. This value enables Exhale to manually strip the path.- Value in
exhale_args
(str) The value of the key
"doxygenStripFromPath"
should be a string representing the (relative or absolute) path to be stripped from the final documentation. As withcontainmentFolder
, relative paths are relative to the Sphinx source directory (whereconf.py
is). Consider the following directory structure:my_project/ ├───docs/ │ conf.py │ └───include/ └───my_project/ common.hpp
In this scenario, if you supplied
"doxygenStripFromPath" = ".."
, then the file page forcommon.hpp
would list its declaration asinclude/my_project/common.hpp
. If you instead set it to be"../include"
, then the file page forcommon.hpp
would list its declaration as justmy_project/common.hpp
.As a consequence, modification of this variable directly affects what shows up in the file view hierarchy. In the previous example, the difference would really just be whether or not all files are nestled underneath a global
include
folder or not.Warning
It is your responsibility to ensure that the value you provide for this configuration is valid. The file view hierarchy will almost certainly break if you give nonsense.
Note
Depending on your project layout, some links may be broken in the above example if you use
"../include"
that work when you use".."
. To get your docs working, revert to".."
. If you’re feeling nice, raise an issue on GitHub and let me know — I haven’t been able to track this one down yet :/Particularly, this seems to happen with projects that have duplicate filenames in different folders, e.g.:
include/ └───my_project/ │ common.hpp │ └───viewing/ common.hpp
Optional Configuration Arguments¶
Build Process Logging, Colors, and Debugging¶
-
exhale.configs.
verboseBuild
= False¶ - Optional
If you are having a hard time getting documentation to build, or say hierarchies are not appearing as they should be, set this to
True
.- Value in
exhale_args
(bool) Set the boolean value to be
True
to include colorized printing at various stages of the build process.Warning
There is only one level of verbosity: excessively verbose. All logging is written to
sys.stderr
. SeealwaysColorize
.Tip
Looking at the actual code of Exhale trying to figure out what is going on? All logging sections have a comment
# << verboseBuild
just before the logging section. So you cangrep -r '# << verboseBuild' exhale/
if you’re working with the code locally.
-
exhale.configs.
alwaysColorize
= True¶ - Optional
Exhale prints various messages throughout the build process to both
sys.stdout
andsys.stderr
. The default behavior is to colorize output always, regardless of if the output is being directed to a file. This is because you can simply usecat
orless -R
. By setting this toFalse
, when redirecting output to a file the color will not be included.- Value in
exhale_args
(bool) The default is
True
because I find color to be something developers should embrace. Simply useless -R
to view colorized output conveniently. While I have a love of all things color, I understand you may not. So just set this toFalse
.Note
There is not and will never be a way to remove the colorized logging from the console. This only controls when
sys.stdout
andsys.stderr
are being redirected to a file.
-
exhale.configs.
generateBreatheFileDirectives
= False¶ - Optional
Append the
.. doxygenfile::
directive from Breathe for every file page generated in the API.- Value in
exhale_args
(bool) If True, then the breathe directive (
doxygenfile
) will be incorporated at the bottom of the file.Danger
This feature is not intended for production release of pages, only debugging.
This feature is “deprecated” in lieu of minimal parsing of the input Doxygen xml for a given documented file. This feature can be used to help determine if Exhale has made a mistake in parsing the file level documentation, but usage of this feature will create many duplicate id’s and the Sphinx build process will be littered with complaints.
Usage of this feature will completely dismantle the links coordinated in all parts of Exhale. Because duplicate id’s are generated, Sphinx chooses where to link to. It seems to reliably choose the links generated by the Breathe File directive, meaning the majority of the navigational setup of Exhale is pretty much invalidated.
Root API Document Customization¶
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
Class Hierarchy
Section 2
4
File Hierarchy
Section 3
5
{{ afterHierarchyDescription }}
Section 4
6
{{ fullApiSubSectionTitle }}
Section 5
7
Unabridged API
Section 6
8
{{ afterBodySummary }}
Section 7
The title of the document will be the required key to
"rootFileTitle"
given toexhale_args
inconf.py
. SeerootFileTitle
.If provided, the value of the key
"afterTitleDescription"
given toexhale_args
will be included. SeeafterTitleDescription
.The Class Hierarchy will be included next. 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"
.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"
.If provided, the value of the key
"afterHierarchyDescription"
given toexhale_args
will be included. SeeafterHierarchyDescription
.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
. SeefullApiSubSectionTitle
.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"
.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
). SeefullToctreeMaxDepth
.Tip
Use
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. SeeafterBodySummary
.
Tip
Where numbers (3), (4), and (7) 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
= None¶ - Optional
Provide a description to appear just after
rootFileTitle
.- Value in
exhale_args
(str) If you want to provide a brief summary of say the layout of the API, or call attention to specific classes, functions, etc, use this. For example, if you had Python bindings but no explicit documentation for the Python side of the API, you could use something like
exhale_args = { # ... other required arguments... "rootFileTitle": "Library API", "afterTitleDescription": textwrap.dedent(''' .. note:: The following documentation presents the C++ API. The Python API generally mirrors the C++ API, but some methods may not be available in Python or may perform different actions. ''') }
-
exhale.configs.
afterHierarchyDescription
= None¶ - Optional
Provide a description that appears after the Class and File hierarchies, but before the full (and usually very long) API listing.
- Value in
exhale_args
(str) Similar to
afterTitleDescription
, only it is included in the middle of the document.
-
exhale.configs.
fullApiSubSectionTitle
= 'Full API'¶ - Optional
The title for the subsection that comes after the Class and File hierarchies, just before the enumeration of the full API.
- Value in
exhale_args
(str) The default value is simply
"Full API"
. Change this to be something else if you so desire.
-
exhale.configs.
afterBodySummary
= None¶ - Optional
Provide a summary to be included at the bottom of the root library file.
- Value in
exhale_args
(str) Similar to
afterTitleDescription
, only it is included at the bottom of the document.Note
The root library document generated can be quite long, depending on your framework. Important notes to developers should be included at the top of the file using
afterTitleDescription
, or after the hierarchies usingafterHierarchyDescription
.
-
exhale.configs.
fullToctreeMaxDepth
= 5¶ - Optional
The generated library root document performs
.. include:: unabridged_api.rst
at the bottom, after the Class and File hierarchies. Insideunabridged_api.rst
, every generated file is included using atoctree
directive to prevent Sphinx from getting upset about documents not being included. This value controls the:maxdepth:
for all of thesetoctree
directives.- Value in
exhale_args
(int) The default value is
5
, but you may want to give a smaller value depending on the framework being documented.Warning
This value must be greater than or equal to
1
. You are advised not to use a value greater than5
.
-
exhale.configs.
listingExclude
= []¶ - Optional
A list of regular expressions to exclude from both the class hierarchy and namespace page enumerations. This can be useful when you want to keep the listings for the hierarchy / namespace pages more concise, but do ultimately want the excluded items documented somewhere.
Nodes whose
name
(fully qualified, e.g.,namespace::ClassName
) matches any regular expression supplied here will:Exclude this item from the class view hierarchy listing.
Exclude this item from the defining namespace’s listing (where applicable).
The “excluded” item will still have it’s own documentation and be linked in the “full API listing”, as well as from the file page that defined the compound (if recovered). Otherwise Sphinx will explode with warnings about documents not being included in any
toctree
directives.
This configuration variable is one size fits all. It was created as a band-aid fix for PIMPL frameworks.
Todo
More fine-grained control will be available in the pickleable writer API sometime in Exhale 1.x.
Note
If you want to skip documentation of a compound in your framework entirely, this configuration variable is not where you do it. See Doxygen PREDEFINED for information on excluding compounds entirely using the doxygen preprocessor.
- Value in
exhale_args
(list) The list can be of variable types, but each item will be compiled into an internal list using
re.compile()
. The arguments forre.compile(pattern, flags=0)
should be specified in order, but for convenience if noflags
are needed for your use case you can just specify a string. For example:exhale_args = { # These two patterns should be equitable for excluding PIMPL # objects in a framework that uses the ``XxxImpl`` naming scheme. "listingExclude": [r".*Impl$", (r".*impl$", re.IGNORECASE)] }
Each item in
listingExclude
may either be a string (the regular expression pattern), or it may be a length two iterable(string pattern, int flags)
.
-
exhale.configs.
unabridgedOrphanKinds
= {'dir', 'file'}¶ - Optional
The list of node kinds to exclude from the unabridged API listing beneath the class and file hierarchies.
- Value in
exhale_args
(list or set of strings) The list of kinds (see
AVAILABLE_KINDS
) that will not be included in the unabridged API listing. The default is to exclude directories and files (which are already in the file hierarchy). Note that if this variable is provided, it will overwrite the default{"dir", "file"}
, meaning if you want to exclude something in addition you need to include"dir"
and"file"
:# In conf.py exhale_args = { # Case 1: _only_ exclude union "unabridgedOrphanKinds": {"union"} # Case 2: exclude union in addition to dir / file. "unabridgedOrphanKinds": {"dir", "file", "union"} }
Tip
See
fullToctreeMaxDepth
, users seeking to reduce the length of the unabridged API should set this value to1
.Warning
If either
"class"
or"struct"
appear inunabridgedOrphanKinds
then both will be excluded. The unabridged API will present classes and structs together.
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
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.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. SeetreeViewBootstrapTextSpanClass
,treeViewBootstrapIconMimicColor
, andtreeViewBootstrapOnhoverColor
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.
Todo
add some pictures of the different hierarchies once this is packaged
-
exhale.configs.
createTreeView
= False¶ - Optional
When set to
True
, clickable hierarchies for the Class and File views will be generated. Set this variable toTrue
if you are generating html output for much more attractive websites!- Value in
exhale_args
(bool) When set to
False
, the Class and File hierarches are just reStructuredText bullet lists. This is rather unattractive, but the default ofFalse
is to hopefully enable non-html writers to still be able to useexhale
.Tip
Using
html_theme = "bootstrap"
(the Sphinx Bootstrap Theme)? Make sure you settreeViewIsBootstrap
toTrue
!
-
exhale.configs.
minifyTreeView
= True¶ - Optional
When set to
True
, the generated html and/or json for the class and file hierarchy trees will be minified.- Value in
exhale_args
(bool) The default value is
True
, which should help page load times for larger APIs. Setting toFalse
should only really be necessary if there is a problem – the minified version will be hard to parse as a human.
-
exhale.configs.
treeViewIsBootstrap
= False¶ - Optional
If the generated html website is using
bootstrap
, make sure to set this toTrue
. The Bootstrap Treeview library will be used.- Value in
exhale_args
(bool) When set to
True
, the clickable hierarchies will be generated using a Bootstrap friendly library.
-
exhale.configs.
treeViewBootstrapTextSpanClass
= 'text-muted'¶ - Optional
What span class to use for the qualifying text after the icon, but before the hyperlink to the actual documentation page. For example,
Struct Foo
in the hierarchy would haveStruct
as the qualifying text (controlled by this variable), andFoo
will be a hyperlink toFoo
’s actual documentation.- Value in
exhale_args
(str) A valid class to apply to a
span
. The actual HTML being generated is something like:<span class="{span_cls}">{qualifier}</span> {hyperlink text}
So if the value of this input was
"text-muted"
, and it was the hierarchy element forStruct Foo
, it would be<span class="text-muted">Struct</span> Foo
The
Foo
portion will receive the hyperlink styling elsewhere.Tip
Easy choices to consider are the contextual classes provided by your bootstrap theme. Alternatively, add your own custom stylesheet to Sphinx directly and create a class with the color you want there.
Danger
No validity checks are performed. If you supply a class that cannot be used, there is no telling what will happen.
-
exhale.configs.
treeViewBootstrapIconMimicColor
= 'text-muted'¶ - Optional
The paragraph CSS class to mimic for the icon color in the tree view.
- Value in
exhale_args
(str) This value must be a valid CSS class for a paragraph. The way that it is used is in JavaScript, on page-load, a “fake paragraph” is inserted with the class specified by this variable. The color is extracted, and then a force-override is applied to the page’s stylesheet. This was necessary to override some aspects of what the
bootstrap-treeview
library does. It’s full usage looks like this:/* Inspired by very informative answer to get color of links: https://stackoverflow.com/a/2707837/3814202 */ /* vvvvvvvvvv what you give */ var $fake_p = $('<p class="icon_mimic"></p>').hide().appendTo("body"); /* ^^^^^^^^^^ */ var iconColor = $fake_p.css("color"); $fake_p.remove(); /* later on */ // Part 2: override the style of the glyphicons by injecting some CSS $('<style type="text/css" id="exhaleTreeviewOverride">' + ' .treeview span[class~=icon] { ' + ' color: ' + iconColor + ' ! important;' + ' }' + '</style>').appendTo('head');
Tip
Easy choices to consider are the contextual classes provided by your bootstrap theme. Alternatively, add your own custom stylesheet to Sphinx directly and create a class with the color you want there.
Danger
No validity checks are performed. If you supply a class that cannot be used, there is no telling what will happen.
-
exhale.configs.
treeViewBootstrapOnhoverColor
= '#F5F5F5'¶ - Optional
The hover color for elements in the hierarchy trees. Default color is a light-grey, as specified by default value of
bootstrap-treeview
’s onhoverColor.- Value in*
exhale_args
(str) Any valid color. See onhoverColor for information.
-
exhale.configs.
treeViewBootstrapUseBadgeTags
= True¶ - Optional
When set to
True
(default), a Badge indicating the number of nested children will be included when 1 or more children are present.When enabled, each node in the json data generated has it’s tags set, and the global showTags option is set to
true
.- Value in
exhale_args
(bool) Set to
False
to exclude the badges. Search forTags as Badges
on the example bootstrap treeview page, noting that if a given node does not have any children, no badge will be added. This is simply because a0
badge is likely more confusing than helpful.
-
exhale.configs.
treeViewBootstrapExpandIcon
= 'glyphicon glyphicon-plus'¶ - Optional
Global setting for what the “expand” icon is for the bootstrap treeview. The default value here is the default of the
bootstrap-treeview
library.- Value in
exhale_args
(str) See the expandIcon description of
bootstrap-treeview
for more information.Note
Exhale handles wrapping this in quotes, you just need to specify the class (making sure that it has spaces where it should). Exhale does not perform any validity checks on the value of this variable. For example, you could use something like:
exhale_args = { # ... required / other optional args ... # you can set one, both, or neither. just showing both in same example # set the icon to show it can be expanded "treeViewBootstrapExpandIcon": "glyphicon glyphicon-chevron-right", # set the icon to show it can be collapsed "treeViewBootstrapCollapseIcon": "glyphicon glyphicon-chevron-down" }
-
exhale.configs.
treeViewBootstrapCollapseIcon
= 'glyphicon glyphicon-minus'¶ - Optional
Global setting for what the “collapse” icon is for the bootstrap treeview. The default value here is the default of the
bootstrap-treeview
library.- Value in
exhale_args
(str) See the collapseIcon description of
bootstrap-treeview
for more information. SeetreeViewBootstrapExpandIcon
for how to specify this CSS class value.
-
exhale.configs.
treeViewBootstrapLevels
= 1¶ - Optional
The default number of levels to expand on page load. Note that the
bootstrap-treeview
default levels value is2
.1
seems like a safer default for Exhale since the value you choose here largely depends on how you have structured your code.- Value in
exhale_args
(int) An integer representing the number of levels to expand for both the Class and File hierarchies. This value should be greater than or equal to
1
, but no validity checks are performed on your input. Buyer beware.
-
exhale.configs.
_class_hierarchy_id
= 'class-treeView'¶ The
id
attribute of the HTML element associated with the Class Hierarchy whencreateTreeView
isTrue
.When
treeViewIsBootstrap
isFalse
, thisid
is attached to the outer-mostul
.For bootstrap, an empty
div
is inserted with thisid
, which will be the anchor point for thebootstrap-treeview
library.
-
exhale.configs.
_file_hierarchy_id
= 'file-treeView'¶ The
id
attribute of the HTML element associated with the Class Hierarchy whencreateTreeView
isTrue
.When
treeViewIsBootstrap
isFalse
, thisid
is attached to the outer-mostul
.For bootstrap, an empty
div
is inserted with thisid
, which will be the anchor point for thebootstrap-treeview
library.
-
exhale.configs.
_bstrap_class_hierarchy_fn_data_name
= 'getClassHierarchyTree'¶ The name of the JavaScript function that returns the
json
data associated with the Class Hierarchy whencreateTreeView
isTrue
andtreeViewIsBootstrap
isTrue
.
-
exhale.configs.
_bstrap_file_hierarchy_fn_data_name
= 'getFileHierarchyTree'¶ The name of the JavaScript function that returns the
json
data associated with the File Hierarchy whencreateTreeView
isTrue
andtreeViewIsBootstrap
isTrue
.
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’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
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. See File 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. 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
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
generateBreatheFileDirectives
toTrue
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.
-
exhale.configs.
includeTemplateParamOrderList
= False¶ - Optional
For Classes and Structs (only), Exhale can provide a numbered list enumeration displaying the template parameters in the order they should be specified.
- Value in
exhale_args
(bool) This feature can be useful when you have template classes that have many template parameters. The Breathe directives will include the parameters in the order they should be given. However, if you have a template class with more than say 5 parameters, it can become a little hard to read.
Note
This configuration is all or nothing, and applies to every template Class / Struct. Additionally, no
tparam
documentation is displayed with this listing. Just the types / names they are declared as (and default values if provided).This feature really only exists as a historical accident.
Warning
As a consequence of the (hacky) implementation, if you use this feature you commit to HTML output only. Where applicable, template parameters that generate links to other items being documented only work in HTML.
-
exhale.configs.
pageLevelConfigMeta
= None¶ - Optional
reStructuredText allows you to employ page-level configurations. These are included at the top of the page, before the title.
- Value in
exhale_args
(str) An example of one such feature would be
":tocdepth: 5"
. To be honest, I’m not sure why you would need this feature. But it’s easy to implement, you just need to make sure that you provide valid reStructuredText or every page will produce errors.See the Field Lists guide for more information.
-
exhale.configs.
repoRedirectURL
= None¶ Todo
This feature is NOT implemented yet! Hopefully soon. It definitely gets under my skin. It’s mostly documented just to show up in the
todolist
for me ;)- Optional
When using the Sphinx RTD theme, there is a button placed in the top-right saying something like “Edit this on GitHub”. Since the documents are all being generated dynamically (and not supposed to be tracked by
git
), the links all go nowhere. Set this so Exhale can try and fix this.- Value in
exhale_args
(str) The url of the repository your documentation is being generated from.
Warning
Seriously this isn’t implemented. I may not even need this from you. The harder part is figuring out how to map a given nodes “
def_in_file
” to the correct URL. I should be able to get the URL fromgit remote
and construct the URL from that andgit branch
. Probably just some path hacking withgit rev-parse --show-toplevel
and comparing that todoxygenStripFromPath
?Please feel free to add your input here.
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:
contentsDirectives
sets globally whether or not any.. contents::
directives are generated.contentsTitle
determines the title of these directives. The default is the reStructuredText default:Contents
.contentsSpecifiers
provides the specifications to apply to the.. contents::
directives. For stylistic reasons, the specifiers Exhale defaults to are:local:
and:backlinks: none
.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 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 setcontentsTitle
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
= True¶ - Optional
Include a
.. contents::
directive beneath the title on pages that have potential to link to a decent number of documents.- Value in
exhale_args
(bool) By default, Exhale will include a
.. contents::
directive on the individual generated pages for the types specified bykindsWithContentsDirectives
. Set this toFalse
to disable globally.See the Using Contents Directives section for all pieces of the puzzle.
-
exhale.configs.
contentsTitle
= 'Contents'¶ - Optional
The title of the
.. contents::
directive for an individual file page, when it’skind
is in the list specified bykindsWithContentsDirectives
andcontentsDirectives
isTrue
.- Value in
exhale_args
(str) The default (for both Exhale and reStructuredText) is to label this as
Contents
. You can choose whatever value you like. If you prefer to have no title for the.. contents::
directives, specify the empty string.Note
Specifying the empty string only removes the title when
":local:"
is present incontentsSpecifiers
. See the Using Contents Directives section for more information.
-
exhale.configs.
contentsSpecifiers
= [':local:', ':backlinks: none']¶ - Optional
The specifications to apply to
.. contents::
directives for the individual file pages when it’skind
is in the list specified bykindsWithContentsDirectives
andcontentsDirectives
isTrue
.- Value in
exhale_args
(list) A (one-dimensional) list of strings that will be applied to any
.. contents::
directives generated. Provide the empty list if you wish to have no specifiers added to these directives. See the Using Contents Directives section for more information.
-
exhale.configs.
kindsWithContentsDirectives
= ['file', 'namespace']¶ - Optional
The kinds of compounds that will include a
.. contents::
directive on their individual library page. The default is to generate one for Files and Namespaces. Only takes meaning whencontentsDirectives
isTrue
.- Value in
exhale_args
(list) Provide a (one-dimensional)
list
ortuple
of strings of the kinds of compounds that should include a.. contents::
directive. Each kind given must one of the entries inAVAILABLE_KINDS
.For example, if you wanted to enable Structs and Classes as well you would do something like:
# in conf.py exhale_args = { # ... required / optional args ... "kindsWithContentsDirectives": ["file", "namespace", "class", "struct"] }
Note
This is a “full override”. So if you want to still keep the defaults of
"file"
and"namespace"
, you must include them yourself.
Breathe Customization¶
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`, *BERORE* 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
.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.
-
exhale.configs.
customSpecificationsMapping
= None¶ - Optional
See the Customizing Breathe Output section for how to use this.
- Value in
exhale_args
(dict) The dictionary produced by calling
makeCustomSpecificationsMapping()
with your custom function.
-
exhale.configs.
_closure_map_sanity_check
= 'blargh_BLARGH_blargh'¶ See
makeCustomSpecificationsMapping()
implementation, this is inserted to help enforce that Exhale made the dictionary going intocustomSpecificationsMapping
.
Doxygen Execution and Customization¶
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
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 byDEFAULT_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 forexhaleUseDoxyfile
for items you need to make sure agree with the configurations you have applied elsewhere to Breathe / Exhale.
-
exhale.configs.
_doxygen_xml_output_directory
= None¶ The absolute path the the root level of the doxygen xml output. If the path to the
index.xml
file created by doxygen was./doxyoutput/xml/index.xml
, then this would simply be./doxyoutput/xml
.Note
This is the exact same path as
breathe_projects[breathe_default_project]
, only it is an absolute path.
-
exhale.configs.
exhaleExecutesDoxygen
= False¶ - Optional
Have Exhale launch Doxygen when you execute
make html
.- Value in
exhale_args
(bool) Set to
True
to enable launching Doxygen. You must set eitherexhaleUseDoxyfile
orexhaleDoxygenStdin
.
-
exhale.configs.
exhaleUseDoxyfile
= False¶ - Optional
If
exhaleExecutesDoxygen
isTrue
, this tells Exhale to use your ownDoxyfile
. The encouraged approach is to useexhaleDoxygenStdin
.- Value in
exhale_args
(bool) Set to
True
to have Exhale use yourDoxyfile
.Note
The
Doxyfile
must be in the same directory asconf.py
. Exhale will change directories to here before launching Doxygen when you have separate source and build directories for Sphinx configured.Warning
No sanity checks on the
Doxyfile
are performed. If you are using this option you need to verify two parameters in particular:OUTPUT_DIRECTORY
is configured so thatbreathe_projects[breathe_default_project]
agrees. See the Mapping of Project Names to Doxygen XML Output Paths section.STRIP_FROM_PATH
is configured to be identical to what is specified withdoxygenStripFromPath
.
I have no idea what happens when these conflict, but it likely will never result in valid documentation.
-
exhale.configs.
exhaleDoxygenStdin
= None¶ - Optional
If
exhaleExecutesDoxygen
isTrue
, this tells Exhale to use the (multiline string) value specified in this argument in addition to theDEFAULT_DOXYGEN_STDIN_BASE
.- Value in
exhale_args
(str) This string describes your project’s specific Doxygen configurations. At the very least, it must provide
INPUT
. See the Using Exhale to Execute Doxygen section for how to use this in conjunction with the default configurations, as well as how to override them.
-
exhale.configs.
DEFAULT_DOXYGEN_STDIN_BASE
= '\n# If you need this to be YES, exhale will probably break.\nCREATE_SUBDIRS = NO\n# So that only Doxygen does not trim paths, which affects the File hierarchy\nFULL_PATH_NAMES = YES\n# Nested folders will be ignored without this. You may not need it.\nRECURSIVE = YES\n# Set to YES if you are debugging or want to compare.\nGENERATE_HTML = NO\n# Unless you want it...\nGENERATE_LATEX = NO\n# Both breathe and exhale need the xml.\nGENERATE_XML = YES\n# Set to NO if you do not want the Doxygen program listing included.\nXML_PROGRAMLISTING = YES\n# Allow for rst directives and advanced functions e.g. grid tables\nALIASES = "rst=\\verbatim embed:rst:leading-asterisk"\nALIASES += "endrst=\\endverbatim"\n# Enable preprocessing and related preprocessor necessities\nENABLE_PREPROCESSING = YES\nMACRO_EXPANSION = YES\nEXPAND_ONLY_PREDEF = NO\nSKIP_FUNCTION_MACROS = NO\n# extra defs for to help with building the _right_ version of the docs\nPREDEFINED = DOXYGEN_DOCUMENTATION_BUILD\nPREDEFINED += DOXYGEN_SHOULD_SKIP_THIS\n'¶ These are the default values sent to Doxygen along stdin when
exhaleExecutesDoxygen
isTrue
. This is sent to Doxygen immediately before theexhaleDoxygenStdin
provided toexhale_args
in yourconf.py
. In this way, you can override any of the specific defaults shown here.Tip
See the documentation for
exhaleDoxygenStdin
, as well asexhaleUseDoxyfile
. Only one may be provided to theexhale_args
in yourconf.py
.The value of this variable is a multiline string with contents:
# If you need this to be YES, exhale will probably break. CREATE_SUBDIRS = NO # So that only Doxygen does not trim paths, which affects the File hierarchy FULL_PATH_NAMES = YES # Nested folders will be ignored without this. You may not need it. RECURSIVE = YES # Set to YES if you are debugging or want to compare. GENERATE_HTML = NO # Unless you want it... GENERATE_LATEX = NO # Both breathe and exhale need the xml. GENERATE_XML = YES # Set to NO if you do not want the Doxygen program listing included. XML_PROGRAMLISTING = YES # Allow for rst directives and advanced functions e.g. grid tables ALIASES = "rst=\verbatim embed:rst:leading-asterisk" ALIASES += "endrst=\endverbatim" # Enable preprocessing and related preprocessor necessities ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = NO SKIP_FUNCTION_MACROS = NO # extra defs for to help with building the _right_ version of the docs PREDEFINED = DOXYGEN_DOCUMENTATION_BUILD PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS
Note
The above value is presented for readability, when using this variable take note of any leading or trailing
\n
characters.
-
exhale.configs.
exhaleSilentDoxygen
= False¶ - Optional
When set to
True
, the Doxygen output is omitted from the build.- Value in
exhale_args
(bool) Documentation generation can be quite verbose, especially when running both Sphinx and Doxygen in the same process. Use this to silence Doxygen.
Danger
You are heavily discouraged from setting this to
True
. Many problems that may arise through either Exhale or Breathe are because the Doxygen documentation itself has errors. It will be much more difficult to find these when you squelch the Doxygen output.The reason you would do this is for actual limitations on your specific
stdout
(e.g. you are getting a buffer maxed out). The likelihood of this being a problem for you is exceptionally small.
Programlisting Customization¶
-
exhale.configs.
lexerMapping
= {}¶ - Optional
When specified, and
XML_PROGRAMLISTING
is set toYES
in Doxygen (either via yourDoxyfile
orexhaleDoxygenStdin
), this mapping can be used to customize / correct the Pygments lexer used for the program listing page generated for files. Most projects will not need to use this setting.- Value in
exhale_args
(dict) The keys and values are both strings. Each key is a regular expression that will be used to check with
re.match()
, noting that the primary difference betweenre.match()
andre.search()
that you should be aware of is thatmatch
searches from the beginning of the string. Each value should be a valid Pygments lexer.Example usage:
exhale_args { # ... "lexerMapping": { r".*\.cuh": "cuda", r"path/to/exact_filename\.ext": "c" } }
Note
The pattern is used to search the full path of a file, as represented in Doxygen. This is so that duplicate file names in separate folders can be distinguished if needed. The file path as represented in Doxygen is defined by the path to the file, with some prefix stripped out. The prefix stripped out depends entirely on what you provided to
doxygenStripFromPath
.Tip
This mapping is used in
utils.doxygenLanguageToPygmentsLexer
, when provided it is queried first. If you are trying to get program listings for a file that is otherwise not supported directly by Doxygen, you typically want to tell Doxygen to interpret the file as a different language. Take the CUDA case. In my input toexhaleDoxygenStdin
, I will want to set bothFILE_PATTERNS
and append toEXTENSION_MAPPING
:FILE_PATTERNS = *.hpp *.cuh EXTENSION_MAPPING += cuh=c++
By setting
FILE_PATTERNS
, Doxygen will now try and process*.cuh
files. By appending toEXTENSION_MAPPING
, it will treat*.cuh
as C++ files. For CUDA, this is a reasonable choice because Doxygen is generally able to parse the file as C++ and get everything right in terms of member definitions, docstrings, etc. However, now the XML generated by doxygen looks like this:<!-- >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> vvv --> <compounddef id="bilateral__filter_8cuh" kind="file" language="C++">
So Exhale would be default put the program listing in a
.. code-block:: cpp
. By setting this variable inexhale_args
, you can bypass this and get the desired lexer of your choice.Some important notes for those not particularly comfortable or familiar with regular expressions in python:
Note that each key defines a raw string (prefix with
r
):r"pattern"
. This is not entirely necessary for this case, but using raw strings makes it so that you do not have to escape as many things. It’s a good practice to adopt, but for these purposes should not matter all that much.Note the escaped
.
character. This means find the literal.
, rather than the regular expression wildcard for any character. Observe the difference with and without:>>> import re >>> if re.match(r".*.cuh", "some_filecuh.hpp"): print("Oops!") ... Oops! >>> if re.match(r".*\.cuh", "some_filecuh.hpp"): print("Oops!") ... >>>
Without
\.
, the.cuh
matchesecuh
since.
is a wildcard for any character. You may also want to use$
at the end of the expression if there are multiple file extensions involved:r".*\.cuh$"
. The$
states “end-of-pattern”, which in the usage of Exhale means end of line (the compiled regular expressions are not compiled withre.MULTILINE
).Take special care at the beginning of your regular expression. The pattern
r"*\.cuh"
does not compile! You need to user".*\.cuh"
, with the leading.
being required.
-
exhale.configs.
_compiled_lexer_mapping
= {}¶ Internal mapping of compiled regular expression objects to Pygments lexer strings. This dictionary is created by compiling every key in
lexerMapping
. See implementation ofutils.doxygenLanguageToPygmentsLexer
for usage.
Utility Variables¶
-
exhale.configs.
SECTION_HEADING_CHAR
= '='¶ The restructured text H1 heading character used to underline sections.
-
exhale.configs.
SUB_SECTION_HEADING_CHAR
= '-'¶ The restructured text H2 heading character used to underline subsections.
-
exhale.configs.
SUB_SUB_SECTION_HEADING_CHAR
= '*'¶ The restructured text H3 heading character used to underline sub-subsections.
-
exhale.configs.
MAXIMUM_FILENAME_LENGTH
= 255¶ When a potential filename is longer than
255
, a sha1 sum is used to shorten. Note that there is no ubiquitous and reliable way to query this information, as it depends on both the operating system, filesystem, and even the location (directory path) the file would be generated to (depending on the filesystem). As such, a conservative value of255
should guarantee that the desired filename can always be created.
-
exhale.configs.
MAXIMUM_WINDOWS_PATH_LENGTH
= 260¶ The file path length on Windows cannot be greater than or equal to
260
characters.Since Windows’ pathetically antiquated filesystem cannot handle this, they have enabled a “magic” prefix they call an extended-length path. This is achieved by inserting the prefix
\\?\
which allows you to go up to a maximum path of32,767
characters but you may only do this for absolute paths. See Maximum Path Length Limitation for more information.Dear Windows, did you know it is the 21st century?
-
exhale.configs.
_the_app
= None¶ The Sphinx
app
object. Currently unused, saved for availability in future.
-
exhale.configs.
_app_src_dir
= None¶ Do not modify. The location of
app.srcdir
of the Sphinx application, once the build process has begun to execute. Saved to be able to run a few different sanity checks in different places.
-
exhale.configs.
_on_rtd
= True¶ Do not modify. Signals whether or not the build is taking place on ReadTheDocs. If it is, then colorization of output is disabled, as well as the Doxygen output (where applicable) is directed to
/dev/null
as capturing it can cause thesubprocess
buffers to overflow.
Secondary Sphinx Entry Point¶
-
exhale.configs.
apply_sphinx_configurations
(app)[source]¶ This method applies the various configurations users place in their
conf.py
, in the dictionaryexhale_args
. The error checking seems to be robust, and borderline obsessive, but there may very well be some glaring flaws.When the user requests for the
treeView
to be created, this method is also responsible for adding the various CSS / JavaScript to the Sphinx Application to support the hierarchical views.Danger
This method is not supposed to be called directly. See
exhale/__init__.py
for how this function is called indirectly via the Sphinx API.- Parameters
app
(sphinx.application.Sphinx
)The Sphinx Application running the documentation build.