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. See Adding additional extensions.

Configuration source reference

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

from pathlib import Path

from technote.sphinxconf import *  # noqa: F401 F403

from documenteer.conf import (
    extend_static_paths_with_asset_extension,
    get_asset_path,
    get_template_dir,
)

try:
    # Remove the sphinxcontrib-bibtex extension so that we can add it back
    # in the proper order relative to documenteer.ext.githubbibcache.
    extensions.remove("sphinxcontrib.bibtex")  # noqa: F405
except ValueError:
    pass

# Add the GitHub bibfile cache extension before sphinxcontrib-bibtex so
# that it can add bibfiles to the sphinxcontrib-bibtex configuration.
extensions.extend(  # noqa: F405
    [
        "documenteer.ext.jira",
        "documenteer.ext.lsstdocushare",
        "documenteer.ext.mockcoderefs",
        "documenteer.ext.remotecodeblock",
        "documenteer.ext.bibtex",
        "documenteer.ext.githubbibcache",
        "sphinxcontrib.bibtex",
        "sphinx_diagrams",
        "sphinxcontrib.mermaid",
        "sphinx_prompt",
    ]
)

html_static_path: list[str] = [
    get_asset_path("rubin-favicon-transparent-32px.png"),
    get_asset_path("rubin-favicon.svg"),
    get_asset_path("rubin-technote.css"),
    get_asset_path("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"),
]
extend_static_paths_with_asset_extension(html_static_path, "woff2")

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",
}

# Configure bibliography with the bib cache
documenteer_bibfile_cache_dir = ".technote/bibfiles"
documenteer_bibfile_github_repos = [
    {
        "repo": "lsst/lsst-texmf",
        "ref": "main",
        "bibfiles": [
            "texmf/bibtex/bib/lsst.bib",
            "texmf/bibtex/bib/lsst-dm.bib",
            "texmf/bibtex/bib/refs_ads.bib",
            "texmf/bibtex/bib/refs.bib",
            "texmf/bibtex/bib/books.bib",
        ],
    }
]
# Set up bibtex_bibfiles
bibtex_bibfiles = []

# Automatically load local bibfiles in the root directory.
for p in Path.cwd().glob("*.bib"):
    bibtex_bibfiles.append(str(p))

bibtex_default_style = "lsst_aa"
bibtex_reference_style = "author_year"

_id = T.metadata.id  # noqa: F405
if _id is not None:
    html_context[  # noqa: F405
        "editions_url"
    ] = f"https://{_id.lower()}.lsst.io/v/"