documenteer.toml reference#
Rubin’s Sphinx user guide configuration with documenteer.conf.guide uses a documenteer.toml file, located next to the Sphinx conf.py file to configure metadata about the project.
This page describes the schema for this documenteer.toml file.
For a step-by-step guide, see Setting up the Documenteer configuration for Rubin user guides.
[project] table#
The [project] table is where most of the project’s metadata is set.
Required
title#
Required
Name of the project, used as titles throughout the documentation site. The title can be different from the package name, if that’s the local standard.
[project]
title = "Documenteer"
base_url#
Optional Auto set by project.python
The root URL of the documentation project, used to set the canonical URL link rel, which is valuable for search engines.
[project]
base_url = "https://documenteer.lsst.io"
copyright#
Optional
The copyright statement, which should exclude the “Copyright” prefix.
[project]
copyright = "2015-2022 Association of Universities for Research in Astronomy, Inc. (AURA)"
github_url#
Optional Auto set by project.python
The URL for the project’s GitHub source repository. When set, a link to the repository is included in the site’s header.
[project]
github_url = "https://github.com/lsst-sqre/documenteer"
version#
Optional Auto set by project.python
The project’s version, which is set to the standard Sphinx version and release configuration variables.
[project.python]#
Optional
Projects that use a pyproject.toml to set their build metadata can include a [project.python] table in documenteer.toml.
With this, many metadata values are automatically detected — look for Auto set by project.python badges above.
Note
If a value is directly set, such as version, that value will override will override information discovered from the Python project itself.
package#
Required
This is the Python project’s name, as set in the name field of the [project] table in pyproject.toml.
Note that the package name can be different from the Python module name.
Setting this field actives automatic metadata discovery for Python projects.
[project]
[project.python]
package = "documenteer"
documentation_url_key#
Optional
By default the base_url is detected from the Homepage field in the [project.urls] table of pyproject.toml.
If your documentation’s URL is associated with a different field label, set that with documentation_url_key.
github_url_key#
Optional
By default the github_url is detected from the Source field in the [project.urls] table of pyproject.toml.
If your GitHub repository’s URL is associated with a different field label, set that with github_url_key.
[sphinx]#
Optional
This [sphinx] table allows you to set a number of Sphinx configurations that you would normally set through the conf.py file.
rst_epilog_file#
Optional
Set this as a path to a reStructuredText file (relative to documenteer.toml and conf.py) containing substitutions and link targets that are available to all documentation pages.
This configuration sets Sphinx’s rst_epilog configuration.
If set, the file is also included in the Sphinx source ignore list to prevent it from becoming a standalone page.
[sphinx]
rst_epilog_file = "_rst_epilog.rst"
.. _Astropy Project: https://www.astropy.org
.. |required| replace:: :bdg-primary-line:`Required`
.. |optional| replace:: :bdg-secondary-line:`Optional`