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.