Setting up the Documenteer configuration for Rubin user guides

Documenteer provides centralized configuration, documenteer.conf.guide, for Rubin Observatory user guide websites created with Sphinx. This page page shows how to add Documenteer as a Python dependency, install Documenteer’s Sphinx configuration, and then customize that configuration.

Python dependency

First, add documenteer and its guide extra as a dependency to your project. How you do this depends on your project’s packaging structure:

pyproject.toml
[project.optional-dependencies]
dev = [
    "documenteer[guide]"
]
requirements.txt
documenteer[guide]

Create a basic conf.py Sphinx configuration file

At the root of your project’s documentation, usually the docs directory for a software project or the root of a documentation-only repository, the conf.py file configures Sphinx. To use Documenteer’s configuration pre-sets, import the documenteer.conf.guide module into it:

conf.py
from documenteer.conf.guide import *

Create a basic documenteer.toml configuration file

In the same directory as the conf.py file, create a file called documenteer.toml:

documenteer.toml
[project]
title = "Example"
copyright = "2015-2022 Association of Universities for Research in Astronomy, Inc. (AURA)"
base_url = "https://example.lsst.io"
github_url = "https://github.com/lsst/example"

The information from documenteer.toml is used by the documenteer.conf.guide preset to configure values in conf.py for Sphinx.

See documenteer.toml reference for more information.

Tip

If your project is a Python package that uses pyproject.toml, you can skip some of this metadata. See Configuring Python projects in documenteer.toml.

Note

Curious about the toml syntax? Learn more at the official TOML website. Documenteer uses TOML for configuration to match Python’s adoption of toml (such as for pyproject.toml).

Next steps