Setting up the Documenteer configuration for Rubin user guides#

Documenteer provides centralized configuration, 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:

dev = [

Create a basic 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 file configures Sphinx. To use Documenteer’s configuration pre-sets, import the module into it, and then override the details specifically related to your project:
from import *

# General information about the project.
project = "Example"
copyright = (
    "2015-2022 "
    "Association of Universities for Research in Astronomy, Inc. (AURA)"

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
version = "1.0.0"
release = version

# HTML theme option overrides
html_theme_options["icon_links"][0]["url"] = ""
html_theme_options["logo"]["text"] = project

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = project

# A shorter title for the navigation bar.  Default is the same as html_title.
html_short_title = project

Extending the Sphinx extension#

The basic configuration, shown above, sets up Sphinx to work well for most types of Rubin documentation projects. You will likely need to extend that configuration, though. This sections describes a few common scenarios.

In general, structure your customizations so that they add to the configuration presets from If the configuration variable is a list or a dictionary, try to append to that list or dictionary rather than reassigning the whole variable.

Setting the version from your Python package#

Rather than manually setting the version configuration variable, you can set it so match your Python project’s version string. One approach is to use importlib.metadata.version:
from importlib.metadata import version as get_version

from import *

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
version = get_version("example")
release = version

# ... include other configurations

Change example to your Python package’s name.

Adding a package to Intersphinx#

One scenario is adding additional projects to the Intersphinx configuration. For example, to add the Python standard library so that built-in Python APIs can be referenced:
from import *

intersphinx_mapping["python"] = ("", None)

To additionally add the LSST Science Pipelines:
from import *

intersphinx_mapping["python"] = ("", None)

Adding a Sphinx extension#

You can add additional Sphinx extensions to your Sphinx build to make use of custom reStructuredText directives and roles. To add a new extension, append to the extensions list:
from import *


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