Sphinx configuration for technotes

Documenteer provides centralized configuration for technotes. To use these configurations, you must first install Documenteer with the “technote” extra, see installation guide.

Basic configuration

To use Documenteer’s configuration in a Sphinx technote project, create a conf.py file:

from documenteer.conf.technote import *

This configuration uses content from the metadata.yaml file, also in the technote project, to set information such as the title and authors.

Extending your technote’s configuration

You can enhance and customize your technote’s configuration by adding additional lines of Python, after the import statement in your conf.py file. These lines extend, and even replace statements in the configuration provided by Documenteer, which you can see in Configuration source reference, below.

The follow sections point out some common configuration tasks. For more information about Sphinx configuration in general, see the Sphinx documentation.

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 documenteer.conf.technote import *

intersphinx_mapping["python"] = ("https://docs.python.org/3", None)

To additionally add the LSST Science Pipelines:

from documenteer.conf.technote import *

intersphinx_mapping["python"] = ("https://pipelines.lsst.io", 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 documenteer.conf.technote import *

extensions.extend(["sphinx-click"])

Remember that if an additional package needs to be installed, add that dependency to the technote’s requirements.txt file.

Configuration source reference

"""Sphinx configuration for Rubin technotes."""

from technote.sphinxconf import *  # noqa: F401 F403

from documenteer.conf import get_asset_path, get_template_dir

html_static_path: list[str] = [
    get_asset_path("rubin-favicon-transparent-32px.png"),
    get_asset_path("rubin-favicon.svg"),
    get_asset_path("styles/rubin-technote.css"),
    get_asset_path("styles/rubin-technote.css.map"),
    get_asset_path("rsd-assets/rubin-imagotype-color-on-white-crop.svg"),
    get_asset_path("rsd-assets/rubin-imagotype-color-on-black-crop.svg"),
]

html_css_files = ["rubin-technote.css"]

# A list of paths that contain extra templates (or templates that overwrite
# builtin/theme-specific templates).
templates_path = [get_template_dir("technote")]


# Configurations for the technote theme.
html_theme_options = {
    "light_logo": "rubin-imagotype-color-on-white-crop.svg",
    "dark_logo": "rubin-imagotype-color-on-black-crop.svg",
    "logo_link_url": "https://www.lsst.io",
    "logo_alt_text": "Rubin Observatory logo",
}