Usage¶
Using exhale can be simple or involved, depending on how much you want to change and how familiar you are with things like Sphinx, Breathe, Doxygen, etc. At the top level, what you need is:
Your C++ code you want to document, with “proper” Doxygen documentation. Please read the Doxygen Documentation Specifics for common documentation pitfalls, as well as features previously unavailable in standard Doxygen.
A sphinx documentation project ready to go. See the Sphinx Getting Started tutorial for getting that off the ground.
Contents
Quickstart Guide¶
You will need to edit 2 files: conf.py
to configure the extensions, and
index.rst
(or whatever document you choose) to include the generated api in a
toctree
directive.
Setup the Extensions in conf.py
¶
Assuming your Doxygen documentation is in order, and you already have your Sphinx project ready to go, we need to configure the Breathe and Exhale extensions. For this guide I assume the following directory structure:
my_project/
│
├── docs/
│ ├── conf.py
│ └── index.rst
│
├── include/
│ └── common.hpp
│
└── src/
└── common.cpp
This structure is not required, but you’ll need to change values accordingly.
Warning
When using relative paths, these are always relative to conf.py
. In the above
structure I do not have a “separate source and build directory” from Sphinx. If
you do, make sure you are using the correct paths.
# The `extensions` list should already be in here from `sphinx-quickstart`
extensions = [
# there may be others here already, e.g. 'sphinx.ext.mathjax'
'breathe',
'exhale'
]
# Setup the breathe extension
breathe_projects = {
"My Project": "./doxyoutput/xml"
}
breathe_default_project = "My Project"
# Setup the exhale extension
exhale_args = {
# These arguments are required
"containmentFolder": "./api",
"rootFileName": "library_root.rst",
"rootFileTitle": "Library API",
"doxygenStripFromPath": "..",
# Suggested optional arguments
"createTreeView": True,
# TIP: if using the sphinx-bootstrap-theme, you need
# "treeViewIsBootstrap": True,
"exhaleExecutesDoxygen": True,
"exhaleDoxygenStdin": "INPUT = ../include"
}
# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'
# Tell sphinx what the pygments highlight language should be.
highlight_language = 'cpp'
With the above settings, Exhale would produce the docs/api
folder, the file
docs/api/library_root.rst
(among many others), and it would use Doxygen to parse
docs/../include
and save the output in docs/doxyoutput
. Meaning the following
structure would be created:
my_project/
├── docs/
│ ├── api/
│ │ └── library_root.rst
│ │
│ ├── conf.py
│ ├── index.rst
│ │
│ └── doxyoutput/
│ └── xml/
│ └── index.xml
│
├── include/
│ └── common.hpp
│
└── src/
└── common.cpp
Note
You are by no means required to use Exhale to generate Doxygen. If you choose not to I assume you have the wherewithal to figure it out on your own.
Make Your Documentation Link to the Generated API¶
So the final step is, in your index.rst
or some other toctree
directive, tell
Sphinx to link in the generated "{containmentFolder}/{rootFileName}"
document:
.. toctree::
:maxdepth: 2
about
api/library_root
Optional: Create a Proper Clean Target¶
The sphinx-quickstart
utility will create a Makefile
for you, you are advised
to create an explicit clean
target that removes the generated utilities.
You can just as easily specify to
breathe_projects
a path such as_build/doxyoutput/xml
, or../build/doxyoutput/xml
if you have separate source and build directories. This will ensure that amake clean
will delete these.To avoid confusing users who are new to Sphinx, I encourage something in the same directory as
conf.py
for simplicity.The generated API must appear in the Sphinx source directory. If you put it under
_build
, it will not get parsed.
So bust out the Makefile
provided by Sphinx Quickstart and add clean
to the
.PHONY
line, and the clean
target as shown below (assuming you’ve been using
the paths specified above):
.PHONY: help Makefile clean
clean:
rm -rf doxyoutput/ api/
@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Danger
make
requires TAB
characters! If you just copy-pasted that, you got
space characters (sorry).
Note
The above code must appear before the %: Makefile
“catch-all” target that
Sphinx produced by default. Otherwise…well the catch-all target catches all!
Additional Usage and Customization¶
Controlling the Layout of the Generated Root Library Document¶
The main library page (at the path given by "{containmentFolder}/{rootFileName}"
)
that you will link to from your documentation is laid out as follows:
1
{{ rootFileTitle }}
Heading
2
{{ afterTitleDescription }}
Section 1
3
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.
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
Linking to a Generated File¶
Using the linking strategies in this section is primarily for in your website’s
documentation such as index.rst
or usage.rst
(since those are already
reStructuredText documents), or even in the supplemental arguments you supply to
exhale_args
such as afterTitleDescription
(since these
arguments get “pasted” directly onto a generated reStructuredText document).
In the actual code documentation, Breathe is typically able to infer links automatically
(which is really great!), as well as you can also use \ref
from Doxygen if that is
not working.
Where possible, you should prefer using the Doxygen \ref
command.
However, you can also use these in your code documentation provided that you enter a verbatim reStructuredText. See the Doxygen ALIASES section for more information on that.
Suggested reStructuredText Linking Strategy¶
Assuming you have set primary_domain = 'cpp'
(as shown in the
Quickstart Guide), you should be able to use the linking strategies
provided by Sphinx itself without needing to prefix everything with cpp:
.
Some examples:
Action |
Syntax |
---|---|
Linking to a class |
|
Linking to a method of a class |
|
Linking to a member of a class |
|
Linking to a function |
|
Tip
The value of primary_domain
in conf.py
is very important here! If you do
not set it, the default is py
(python). This means that instead of
:class:`namespace::ClassName`
you would need to use
:cpp:class:`namespace::ClassName`
to use a different domain.
A much more thorough walk-through of how the different domains can be used together
(e.g., how to link to a define
or macro) is provided in the companion website’s
Using Intersphinx guide.
Using Exhale’s Internal Links¶
If the above are not working, you can try using the links that Exhale generates to
perform its own internal linkage. These links are much harder to use directly.
However, there are some documented compounds that can only be linked to using these
internal links. These are either because Exhale does not use the corresponding
Breathe directive (e.g., namespace
) or there does not exist an equivalent link
type in the Sphinx C++ domain (file
and dir
).
Linking to the Root API Document¶
Todo
In Exhale v1.0.0 (when full-fledged projects are supported) each heading on this page will receive a formal reStructuredText label to ease the process of linking to this page.
Danger
This has an important consequence for you! If you use the linking strategy described here, when formal reStructuredText labels are introduced, your links will likely break (because it changes the anchor point from the title to the generated label).
The link generated is entirely defined by what you specify to exhale_args
with the
keys rootFileTitle
, rootFileName
and
containmentFolder
. Consider the values
exhale_args = {
"containmentFolder": "./api",
"rootFileName": "library_root.rst",
"rootFileTitle": "Library API"
# ... other arguments ...
}
Exhale will generate the file {containmentFolder}/{rootFileName}
(so
./api/library_root.rst
) with an H1 heading {rootFileTitle}
like so:
Library API
===========
Other stuff generated by Exhale...
To link to the top of this generated document, you can use a reStructuredText link such as
.. html, not rst! ----------vv
.. vvvv
Please see the `full Library API <api/library_root.html#library-api>`_
.. |--------------| |-------------------| |---------| |
.. 1 2 3 4
The hyperlink text generated will be what is before the
<target>
. In this example the hyperlink text will befull Library API
.Inside of the
<angle brackets>
is the actual hyperlink target. Note that this is a relative path here, so the above link would work forindex.rst
, but would not work for saytutorials/getting_started.rst
.Lastly, the anchor point is derived from what you specified as the root file title. The general scheme for how reStructuredText generates these links is basically
target.lower().replace(" ", "-")
, but special symbols are treated differently.The trailing
_
after#library-api>
is required! That’s how reStructuredText hyperlinks work.
Linking to “Special Cases”: namespaces, files, and directories¶
The work for generating these links takes place in
ExhaleRoot.initializeNodeFilenameAndLink
.
The relevant section of the code:
SPECIAL_CASES = ["dir", "file", "namespace"]
if node.kind in SPECIAL_CASES:
if node.kind == "file":
unique_id = node.location
else:
unique_id = node.name
unique_id = unique_id.replace(":", "_").replace(os.sep, "_").replace(" ", "_")
# ... later on ...
if node.kind in SPECIAL_CASES:
node.link_name = "{kind}_{id}".format(kind=node.kind, id=unique_id)
Some examples of links you would use:
namespace foo::bar::baz
:.. node.kind .. |-------| :ref:`namespace_foo__bar__baz` .. || || .. Two underscores between namespaces! .. from: replace(":", "_")
file include/outer_dir/inner/file.hpp
:.. node.kind .. |--| :ref:`file_include_outer_dir_inner_file.hpp`
Note that unlike namespaces,
replace(os.sep, "_")
will only result in a single underscore between directories. Note that spaces are not allowed in the generated links, so they are also replaced with underscores.dir include/outer_dir/inner
:.. node.kind .. |-| :ref:`dir_include_outer_dir_inner`
Treatment is identical to files, with the same considerations for path separator and space replacement.
Linking to Any Other Generated File¶
Warning
Using these links directly may be an exercise in futility. You should be able to use the links described in Suggested reStructuredText Linking Strategy.
The work for generating these links also takes place in
ExhaleRoot.initializeNodeFilenameAndLink
.
The relevant section for these constructs is:
unique_id = node.refid
# ... later on ...
node.link_name = "exhale_{kind}_{id}".format(kind=node.kind, id=unique_id)
This is prefixed with exhale_
because there are potential collisions with using the
Doxygen refid
(Doxygen’s internal “unique identifier scheme”, which is mostly
equivalent to compiler-like C++ name mangling with some potential hashing and
divergences). The collisions come from the fact that Breathe will typically create an
anchor point that is exactly the Doxygen refid
. The Breathe anchors are where the
links such as :class:`namespace::ClassName`
as well as your standard \ref
calls will direct to. This is ideal.
The Exhale links are anchor points to the top of the generated page that has the Breathe directive in its body. These anchor points are used for indexing the tree view.
Tip
If for whatever reason you want to use the Exhale internal links, you can save yourself a lot of time trying to figure out what they might be and just generate the api once. Open up the generated file for the desired node, and look at the top.
.. _exhale_class_somecrazy_thing:
Class ``somecrazy_thing``
=========================
Copy-paste the thing at the top starting with .. _
, noting that in this
particular (hypothetical) example, you would use
:ref:`exhale_class_somecrazy_thing`
without the leading underscore. The
leading .. _
is what tells reStructuredText “I want this to be the name of the
link”.
Note
The internal links changed in a breaking way with Exhale v0.2.0. Unless an exceptionally compelling reason comes up, I hope to never change the internal link generation again.
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.
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.
Customizing Breathe Output¶
The directives for generating the documentation for a given node come from Breathe.
Exhale uses the Breathe defaults for all directives, except for Classes and Structs.
Suppose you are documenting a class namespace::ClassName
. Exhale will produce
the following directive:
.. doxygenclass:: namespace::ClassName
:members:
:protected-members:
:undoc-members:
where the defaults being overridden are to include :protected-members:
as well as
:undoc-members:
. You may, for example, want to also include :private-members:
in your documentation, or override the default settings for other Breathe directives
to control what is displayed.
In order to override these settings, a layer of indirection has to be added. Because Exhale is a Sphinx Extension, it needs to be possible to do something called “Pickle”. The short version of what this means is that you cannot give me a function directly to call, because the Python function object cannot be pickled. The solution is to use the wrapper function I have created that takes your input function and stores all possible inputs and outputs in a dictionary. Details aside, it’s easier than it sounds.
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.
Fully Automated Building¶
It is preferable to have everything generated at once, e.g. if you wish to host your documentation on Read the Docs. Exhale is configured to enable this directly for you, provided that you have the associated configuration variables setup.
Using Exhale to Execute Doxygen¶
To have Exhale launch Doxygen when you run make html
, you will need to set
exhaleExecutesDoxygen
to True
. After setting that, you will
need to choose how Exhale is executing Doxygen. If you already know what you are doing,
continue on. If you’ve never used Doxygen before, skim this, but refer to the
Mastering Doxygen for more information on areas that you may
get confused by.
- Suggested Approach
Provide a (multiline) string to
exhaleDoxygenStdin
. In the Quickstart Guide, the bare minimum needed to get things off the ground was used:INPUT
must be set to tell Doxygen where to look.Tip
If you set
verboseBuild
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.
Executing Doxygen Independently¶
This is another option, just make sure that Doxygen is run before Exhale is. See the note at the bottom of the Quickstart Guide.
Doxygen Documentation Specifics¶
To have Exhale launch Doxygen when you run make html
, you will need to set
exhaleExecutesDoxygen
to True
. After setting that, you will
need to choose how Exhale is executing Doxygen. If you already know what you are doing,
continue on. If you’ve never used Doxygen before, skim this, but refer to the
Mastering Doxygen for more information on areas that you may
get confused by.
- Suggested Approach
Provide a (multiline) string to
exhaleDoxygenStdin
. In the Quickstart Guide, the bare minimum needed to get things off the ground was used:INPUT
must be set to tell Doxygen where to look.Tip
If you set
verboseBuild
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.
File and Namespace Level Documentation in Exhale¶
Since the Breathe file / namespace directives cannot be used, Exhale implements a “best-faith-effort” documentation parser. It includes support for a few basic block-level elements such as listings, but it is definitively not robust. If the file or namespace level documentation is rendering in unexpected ways, this is because your documentation is “too advanced” for Exhale’s mini-parser.
Tip
See the walk()
method for the currently supported Doxygen
formatting being parsed.
However, the solution is easy: use a verbatim reStructuredText environment in the documentation. See how to do that in the Doxygen ALIASES section.
Note
By entering a verbatim RST environment, doxygen commands such as \ref
are no
longer available. Or rather, they will be parsed as-is without actually generating
a link to the desired target. Since you’ve now entered a verbatim RST environment,
you would instead use the Sphinx domain links.
So if you were linking to class namespace::ClassName
using
\ref namespace::ClassName
, this would now change to be
:class:`namespace::ClassName`
. See the Sphinx Cross Referencing Guide
for some more examples. There is also an Intersphinx Guide
available on the companion website with some examples of linking to macros.
Start to finish for Read the Docs¶
Assuming you already had the code that you are generating the API for documented,
navigate to the top-level folder of your repository. Read the Docs (RTD) will be
looking for a folder named either doc
or docs
at the root of your repository
by default:
$ cd ~/my_repo/
$ mkdir docs
Now we are ready to begin.
Generate your sphinx code by using the
sphinx-quickstart
utility. It may look something like the following:$ ~/my_repo/docs> sphinx-quickstart Welcome to the Sphinx 1.6.3 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: ... and a whole lot more ...
This will create the files
conf.py
,index.rst
,Makefile
, andmake.bat
if you are supporting Windows. It will also create the directories_static
and_templates
for customizing the sphinx output.Create a
requirements.txt
file with the lineexhale
so RTD will install it:$ ~/my_repo/docs> echo 'exhale' > requirements.txt
Follow the Quickstart Guide.
Edit
conf.py
to use the RTD Theme or whichever theme you like. From the RTD Theme README, you would do# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if not on_rtd: # only import and set the theme if we're building docs locally import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
Go to the admin page of your RTD website and select the Advanced Settings tab. Make sure the Install your project inside a virtualenv using
setup.py install
button is NOT checked (unless you have asetup.py
at the root of your repository). In the Requirements file box below, enterdocs/requirements.txt
assuming you followed the steps above.I personally prefer to keep the
requirements.txt
hidden in thedocs
folder so that it is implicit that those are only requirements for building the docs, and not the actual project itself.
And you are done. Make sure you git add
all of the files in your new docs
directory, RTD will clone your repository / update when you push commits. You can
build it locally using make html
in the current directory, but make sure you do not
add the _build
directory to your git repository.
Tip
While you are at it, you should probably add to your .gitignore
:
docs/_build
# wherever you told breathe_projects to look
docs/doxyoutput
# wherever you told Exhale containmentFolder is
docs/api
I hope that the above is successful for you, it looks like a lot but it’s not too bad… right?