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#