Sphinx config.py

Synopsis

Sphinx config file.

Description

This is an early version of a Sphinx RTD theme boilerplate config.py file. Future versions will be better organized and will, eventually, be configurable from yaml.

Reasons for this config.py structure:

• enforce precedence

• compartmentalized configuration topics

• increase maintainability

• preparation for implementing dynamic variable instantiation:

  • configuration will move to yaml format

  • Sphinx API will be used to manage configuration entities

Platform

Unix, Windows, python >=v3.5.3

Dependencies

alabaster>=0.7.12
Babel>=2.6.0
certifi>=2019.3.9
chardet>=3.0.4
docutils>=0.14
editfrontmatter>=0.0.1
idna>=2.8
imagesize>=1.1.0
Jinja2>=2.10.1
m2r>=0.2.1
MarkupSafe>=1.1.1
mistune>=0.8.4
oyaml>=0.9
packaging>=19.0
Pygments>=2.4.0
pyparsing>=2.4.0
pytz>=2019.1
PyYAML>=5.1
requests>=2.22.0
six>=1.12.0
snowballstemmer>=1.2.1
Sphinx>=2.0.1
sphinx-rtd-theme>=0.4.3
sphinxcontrib-applehelp>=1.0.1
sphinxcontrib-devhelp>=1.0.1
sphinxcontrib-htmlhelp>=1.0.2
sphinxcontrib-jsmath>=1.0.1
sphinxcontrib-qthelp>=1.0.2
sphinxcontrib-serializinghtml>=1.1.3
urllib3>=1.25.3

License

Sphinx RTD Theme Project Owner: MIT

RTD Boilerplate: `MIT

EditFrontMatter: `MIT

Module Author

Karl N. Redman

homepage

Sphinx RTD Boilerplate

EditFrontMatter

Current Release

version: 0.0.1

New in version 0.0.1: Initial Version

Note

Module attributes below

path_setup()

Path setup: If extensions (or modules to document with autodoc) are in another directory, add these directories to sys.path here. If the directory is relative to the documentation root, use os.path.abspath to make it absolute, like shown here.

sphinx_setup()

Sphinx setup config variables

runtime_setup()

Standard boilerplate variables

extensions_setup()

Add any Sphinx extension module names here, as strings. They can be extensions coming with Sphinx (named ‘sphinx.ext.*’) or your custom ones.

Extensions (alphabetical)

• m2r

  • M2R converts a markdown file including reStructuredText (rst) markups to a valid rst format.

  • Likely to cause warnings for some markdown pygments highlighting code blocks.

• sphinx.ext.autodoc

  • Include documentation from docstrings.

• sphinx.ext.autosummary

  • Generate autodoc summaries

  • Likely to cause duplicat object definition warnings that seem to be unfixable.

• sphinx.ext.doctest

  • Test snippets in the documentation

• sphinx.ext.githubpages

  • Publish HTML docs in GitHub Pages

• sphinx.ext.intersphinx

  • Link to other projects’ documentation

• sphinx.ext.napoleon

  • Support for NumPy and Google style docstrings.

• sphinx.ext.todo

  • Support for todo items

• sphinx.ext.viewcode

  • Add links to highlighted source code

html_config()

Sphinx HTML config

html_theme_options_config()

extensions_config()

rst_epilog_config()

A string of reST that will be included at the end of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_prolog).

Note that this string will not replace document titles due to the order by which files are processed relative to hierarchical toctree directives.

setup(app)

setup custom directives for execution of the app, e.g. app.add_stylesheet()

References

Sphinx api documentation