Extending conf.py directly#
The basic configurations, through
documenteer.toml and documenteer.conf.guide, set up Sphinx to work well for most types of Rubin documentation projects.
You will likely need to extend that configuration, though.
This page describes a few common scenarios.
Using the [sphinx] table in documenteer.toml#
conf.py, check the documenteer.toml reference to see if there’s support for a particular Sphinx configuration.
For example, the
[sphinx] table includes support for adding Sphinx extensions, adding projects to the Intersphinx mapping, among other capabilities.
If the configuration isn’t supported by
documenteer.toml, you can edit the Sphinx
conf.py configuration file directly.
When Sphinx runs, the
conf.py configuration file is “executed” so that all variables in the global namespace become Sphinx configurations.
The documenteer.conf.guide configuration presets populate the global namespace.
Therefore you can add or edit those configurations by setting variables after the import of documenteer.conf.guide.
For example, to change the number of times the linkcheck builder will try a URL:
from documenteer.conf.guide import * linkcheck_retries = 2
See the list of Sphinx configuration in the Sphinx documentation. Extensions can also declare additional configurations, see their documentation for listings.