How this Version of ckpttncpp was Created¶
For convenience, I’m going to inline the code used in this configuration from
conf.py
here. The three main things you need to do here are
The
requirements.txt
used on read the docs.Setup the
breathe
andexhale
extensions.Choose your
html_theme
, which affects what you choose for theexhale
side.
Refer to the Start to finish for Read the Docs tutorial for getting everything setup on RTD.
requirements.txt
¶
# for testing the master branch
# git+git://github.com/svenevs/exhale.git#egg=exhale
# See: https://exhale.readthedocs.io/en/latest/#exhale-version-compatibility-with-python-sphinx-and-breathe
sphinx>=2.0
sphinx-bootstrap-theme>=0.4.0
breathe>=4.13.0
exhale
Extension Setup¶
# Tell Sphinx to use both the `breathe` and `exhale` extensions
extensions = [
'breathe',
'exhale'
]
# Setup the `breathe` extension
breathe_projects = {"ckpttncpp": "./doxyoutput/xml"}
breathe_default_project = "ckpttncpp"
# Setup the `exhale` extension
# import textwrap
exhale_args = {
############################################################################
# These arguments are required. #
############################################################################
"containmentFolder": "./api",
"rootFileName": "library_root.rst",
"rootFileTitle": "Library API",
"doxygenStripFromPath": "../lib/include",
############################################################################
# Suggested optional arguments. #
############################################################################
"createTreeView": True,
"exhaleExecutesDoxygen": True,
"exhaleDoxygenStdin": textwrap.dedent('''
INPUT = ../lib/include
# For this code-base, the following helps Doxygen get past a macro
# that it has trouble with. It is only meaningful for this code,
# not for yours.
PREDEFINED += NAMESPACE_BEGIN(arbitrary)="namespace arbitrary {"
PREDEFINED += NAMESPACE_END(arbitrary)="}"
'''),
############################################################################
# HTML Theme specific configurations. #
############################################################################
# Fix broken Sphinx RTD Theme 'Edit on GitHub' links
# Search for 'Edit on GitHub' on the FAQ:
# http://exhale.readthedocs.io/en/latest/faq.html
"pageLevelConfigMeta": ":github_url: https://github.com/svenevs/exhale-companion",
############################################################################
# Main library page layout example configuration. #
############################################################################
"afterTitleDescription": textwrap.dedent(u'''
Welcome to the developer reference to Exhale Companion. The code being
documented here is largely meaningless and was only created to test
various corner cases e.g. nested namespaces and the like.
.. note::
The text you are currently reading was fed to ``exhale_args`` using
the :py:data:`~exhale.configs.afterTitleDescription` key. Full
reStructuredText syntax can be used.
.. tip::
Sphinx / Exhale support unicode! You're ``conf.py`` already has
it's encoding declared as ``# -*- coding: utf-8 -*-`` **by
default**. If you want to pass Unicode strings into Exhale, simply
prefix them with a ``u`` e.g. ``u"👽😱💥"`` (of course you would
actually do this because you are writing with åçćëñtß or
non-English 寫作 😉).
'''),
"afterHierarchyDescription": textwrap.dedent('''
Below the hierarchies comes the full API listing.
1. The text you are currently reading is provided by
:py:data:`~exhale.configs.afterHierarchyDescription`.
2. The Title of the next section *just below this* normally defaults to
``Full API``, but the title was changed by providing an argument to
:py:data:`~exhale.configs.fullApiSubSectionTitle`.
3. You can control the number of bullet points for each linked item on
the remainder of the page using
:py:data:`~exhale.configs.fullToctreeMaxDepth`.
'''),
"fullApiSubSectionTitle": "Custom Full API SubSection Title",
"afterBodySummary": textwrap.dedent('''
You read all the way to the bottom?! This text is specified by giving
an argument to :py:data:`~exhale.configs.afterBodySummary`. As the docs
state, this summary gets put in after a **lot** of information. It's
available for you to use if you want it, but from a design perspective
it's rather unlikely any of your users will even see this text.
'''),
############################################################################
# Individual page layout example configuration. #
############################################################################
# Example of adding contents directives on custom kinds with custom title
"contentsTitle": "Page Contents",
"kindsWithContentsDirectives": ["class", "file", "namespace", "struct"],
# This is a testing site which is why I'm adding this
"includeTemplateParamOrderList": True,
############################################################################
# useful to see ;)
"verboseBuild": True
}
# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'
# Tell sphinx what the pygments highlight language should be.
highlight_language = 'cpp'
HTML Theme Setup¶
# The name of the Pygments (syntax highlighting) style to use.
# `sphinx` works very well with the RTD theme, but you can always change it
pygments_style = 'sphinx'
# 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_bootstrap_theme
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()