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"

github_default_branch

Optional

The default branch on GitHub. Default is main. Used in conjunction with the “Edit on GitHub” link, see sphinx.show_github_edit_link.

version

Optional Auto set by project.python

The project’s version, which is set to the standard Sphinx version and release configuration variables.

[project.openapi]

Optional

Web applications that use OpenAPI can include a [project.openapi] table in documenteer.toml to embed a Redoc subsite of the API documentation (see Embedding a Redoc subsite for OpenAPI (HTTP API) documentation).

doc_path

Optional

The docname (without extension) of the page in the Sphinx documentation tree where the Redoc HTML page is built. Default is api.

openapi_path

Optional

The path to the OpenAPI specification file, relative to the Sphinx configuration file, conf.py. If [project.openapi.generator] is set, this is the path where the OpenAPI specification file is generated.

[project.openapi.generator]

Optional

If this table is provided, the OpenAPI specification file is generated from a user-specified Python function. This is useful for FastAPI and similar applications where the OpenAPI specification is generated from the application code.

function

Required

The Python function that generates the OpenAPI specification file. This function must return the OpenAPI specification as a JSON-serialized string.

Specify the function as <module>:<function>. For example, if the function called create_openapi is in the main.py module of the example package, the value would be "example.main:create_openapi".

[project.openapi.generator]
function = "example.main:create_openapi"

positional_args

Optional

Positional arguments to pass to the function, if required.

[project.openapi.generator]
function = "example.main:create_openapi"
positional_args = ["arg1", "arg2"]

keyword_args

Optional

Keyword arguments to pass to the function, if required.

[project.openapi.generator]
function = "example.main:create_openapi"
keyword_args = {kwarg1 = "value1", kwarg2 = "value2"}

[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.

See also

Configuring Python projects in documenteer.toml

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.

disable_primary_sidebars

Optional

On some pages the default sidebar (on the left) is inappropriate, such as index pages that already contain a table of contents as their main content. In that case, you can set individual pages or globs (without extensions) of pages that are shown without the primary sidebar. The default is ["index"] to remove the sidebar from the homepage.

[sphinx]
disable_primary_sidebars = [
  "**/index",
  "changelog"
]

Note

This configuration is for the primary sidebar, on the left side, containing side or section-level navigation links. To remove the page-level contents sidebar, on the right side, add :html_theme.sidebar_secondary.remove: to the page’s file metadata.

exclude

Optional

A list of file paths, relative to conf.py, to exclude from the Sphinx build. This configuration is often used to prevent file unrelated to the documentation from being accidentally included in the site build. documenteer.conf.guide includes common files and directories, so you may not need to modify this configuration in standard situations.

extensions

Optional

A list of Sphinx extensions to append to the extensions included in the Documenteer configuration preset (see documenteer.conf.guide). Duplicate extensions are ignored.

Remember that additional packages may need to be added to your project’s Python dependencies (such as in a requirements.txt or pyproject.toml file).

nitpicky

Optional

Set to true to escalate Sphinx warnings to errors, which is useful for leveraging CI to notify you of any syntax errors. The default is false.

[sphinx]
nitpicky = true

See nitpick_ignore and nitpick_ignore_regex for ways to suppress unavoidable errors.

nitpick_ignore

Optional

A list of Sphinx warnings to ignore. Each item is a tuple of two items:

1. type, often the reStructuredText role or directive creating the error/warning.

2. target, often the argument to the reStructuredText role.

[sphinx]
nitpick_ignore = [
  ["py:class", "fastapi.applications.FastAPI"],
  ["py:class", "httpx.AsyncClient"],
  ["py:class", "pydantic.main.BaseModel"],
]

This configuration extends the Sphinx nitpick_ignore configuration.

nitpick_ignore_regex

Optional

A list of Sphinx warnings to ignore, formatted as regular expressions. Each item is a tuple of two items:

1. type, a regular expression of the warning type.

2. target, a regular expression of the warning target.

[sphinx]
nitpick_ignore_regex = [
  ['py:.*', 'fastapi.*'],
  ['py:.*', 'httpx.*'],
  ['py:.*', 'pydantic*'],
]

Tip

Use single quotes for literal strings in TOML.

This configuration extends the Sphinx nitpick_ignore_regex configuration.

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.

documenteer.toml

 [sphinx]
 rst_epilog_file = "_rst_epilog.rst"

_rst_epilog.rst

.. _Astropy Project: https://www.astropy.org

.. |required| replace:: :bdg-primary-line:`Required`
.. |optional| replace:: :bdg-secondary-line:`Optional`

See Using the rst epilog for common links and substitutions.

python_api_dir

Optional

Set this to the directory where Python API documentation is generated, through automodapi. The default value is api, which is a good standard for Python projects with a public API.

If the Python API is oriented towards contributors, such as in an application or service, you can change the default:

documenteer.toml

[sphinx]
python_api_dir = "dev/api/contents"

[sphinx.redirects]

Optional

A table of paths to redirect to other paths. Use this setting to redirect old page locations to the new locations when a documentation site is reorganized.

documenteer.toml

[sphinx.redirects]
"old/path" = "new/path"
"old/path2" = "new/path2"

[sphinx.theme]

Optional

Configurations related to the Sphinx HTML theme.

header_links_before_dropdown

Optional

Number of links to show in the navigation head before folding extra items into a “More” dropdown. The default is 5.

If the section titles are long you may need to reduce this number.

show_github_edit_link

Optional

Default is true, so that each page contains a link to edit its source on GitHub.

This configuration requires information about the GitHub repository from these other configurations:

• project.github_url

• project.github_default_branch

[sphinx.intersphinx]

Optional

Configurations related to Intersphinx for linking to other Sphinx projects.

[sphinx.intersphinx.projects]

Optional

A table of Sphinx projects. The labels are targets for the external role. The values are URLs to the root of Sphinx documentation projects.

[sphinx.intersphinx.projects]
sphinx = "https://www.sphinx-doc.org/en/master/"
documenteer = "https://documenteer.lsst.io"
python = "https://docs.python.org/3/"

See the Intersphinx documentation for details on linking to other Sphinx projects.

[sphinx.linkcheck]

Optional

Configurations related to Sphinx’s linkcheck builder.

ignore

Optional

List of URL regular expressions patterns to ignore checking. These are appended to the linkcheck_ignore configuration.