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"

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.

show_last_updated#

Optional

Default is true, so that each page shows a “Last updated on <date>.” timestamp at the bottom of each page.

See also

“Last updated” page timestamps for how the date is computed and the extension’s Sphinx configuration values.

The date is computed from the page’s Git commit history, not the filesystem modification time (which is meaningless in CI). It is the most recent commit date across the page’s own source file and any files the page pulls in with include or literalinclude directives, so editing an included snippet updates every page that uses it. Because the date is the last commit date, uncommitted local edits don’t change it; a page whose source has never been committed shows no timestamp.

Set this to false to hide the timestamp:

documenteer.toml#
[sphinx.theme]
show_last_updated = false

Important

Because the date comes from the Git history, your CI build must check out the full commit history. With actions/checkout, set fetch-depth: 0:

.github/workflows/ci.yaml#
- uses: actions/checkout@v6
  with:
    fetch-depth: 0

A shallow clone (the default) only fetches the most recent commit, so every page would otherwise report the same, incorrect date. To avoid publishing misleading data, Documenteer detects a shallow clone, omits the “Last updated” timestamp from every page, and emits a single build warning telling you to set fetch-depth: 0.

[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 for the linkcheck builder, which checks the external links in the documentation.

By default, Documenteer replaces Sphinx’s built-in linkcheck builder with a builder backed by the Ook link-check service (the documenteer.ext.linkcheckservice extension). Instead of checking every link in-process, the builder submits the project’s external links to the service and polls for the results. The service caches results and retries failing links over time, so documentation builds no longer fail on transient third-party outages.

The service requires a bearer token for the Ook API, read from the OOK_TOKEN environment variable. If the token is missing or rejected, the builder falls back to Sphinx’s built-in in-process linkcheck builder in every mode, so link checking still runs for projects that haven’t configured the token (for example, fork pull requests where secrets are unavailable, or CI that doesn’t forward the token). The built-in check’s own result then decides the build’s exit status. If instead the service is unreachable or the polling budget is exhausted, the build degrades gracefully by default: the builder emits a warning and the build finishes with a zero exit status. Set strict to true to fail the build on those service problems instead. Links the service reports as broken always fail the build, regardless of the strict setting.

Note

Technotes use the same service-backed linkcheck builder, but technotes don’t read documenteer.toml, so the settings below don’t apply to them. Instead, the technote configuration preset derives the origin base URL from the canonical_url setting in the [technote] table of technote.toml, falling back to the technote’s handle as https://<handle>.lsst.io. The other settings keep their defaults.

A technote can override any of these settings through the corresponding documenteer_linkcheck_* configuration values in conf.py, after the from documenteer.conf.technote import * line. For example, documenteer_linkcheck_use_service = False restores Sphinx’s built-in linkcheck builder, and documenteer_linkcheck_strict = True enables strict mode.

ignore#

Optional

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

Ignored URLs apply to both the service-backed builder (matching URLs are never submitted to the service) and Sphinx’s built-in linkcheck builder.

use_service#

Optional

Whether to check links with the Ook link-check service instead of Sphinx’s built-in linkcheck builder. Default is true.

Set this to false as an escape hatch to restore Sphinx’s built-in linkcheck builder, which checks each link in-process and doesn’t require an Ook API token:

[sphinx.linkcheck]
use_service = false

With use_service = false the built-in builder is selected outright and the service is never contacted, even when an OOK_TOKEN is set. This differs from the automatic token fallback under the default use_service = true, where the builder uses the service when a token works and only falls back to the built-in in-process check when the OOK_TOKEN is missing or rejected.

service_url#

Optional

Base URL of the Ook API that hosts the link-check service. Default is https://roundtable.lsst.cloud/ook.

poll_budget#

Optional

Maximum time, in seconds, to wait for link-check results from the service. Default is 300.

If the budget is exhausted before the service completes the check, the build emits a warning and continues — or fails, if strict is true.

strict#

Optional

Whether genuine link-check service problems fail the build. Default is false: when the service is unreachable or the poll_budget is exhausted, the builder emits a warning and the build finishes with a zero exit status. Set this to true to fail the build on those conditions instead:

[sphinx.linkcheck]
strict = true

This setting only gates genuine service availability problems. A missing or rejected OOK_TOKEN is not one of them: rather than failing, the builder falls back to Sphinx’s built-in in-process linkcheck builder in every mode (including under strict), so link checking still runs. Links the service reports as broken always fail the build, regardless of this setting.

origin_base_url#

Optional

The origin base URL the links are submitted for: the full base URL of the published website (for example, https://documenteer.lsst.io). The link-check service uses the origin to associate the submitted URLs with the website. By default the origin is the project.base_url setting, so most guides don’t need to set this override. The URL is normalized the way the service normalizes origins: the host is lowercased and any trailing slash is stripped.

[sphinx.linkcheck]
origin_base_url = "https://documenteer.lsst.io"

This page was last modified on .