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.
documenteer and its
guide extra as a dependency to your project.
How you do this depends on your project’s packaging structure:
[project.optional-dependencies] dev = [ "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:
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
[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.
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.
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
If you are setting up a Python project, see Configuring Python projects in documenteer.toml.
For additional Sphinx configuration control, see Extending conf.py directly.