Configuring the Sphinx build#

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, the Sphinx conf.py file must contain the following import:

conf.py#
from documenteer.conf.technote import *

This configuration uses content from the technote.toml file, also in the technote repository, along with defaults in Documenteer to configure the technote build.

Customizing the Sphinx build#

Most technote projects don’t need to customize the Sphinx build beyond the defaults provided by Documenteer. If you do need to customize the build, there are two ways to do so: technote.toml and conf.py.

With technote.toml#

The recommended way to customize the build, where possible, is to through the [technote.sphinx] table in the technote.toml file. Some key configurations provided through technote.toml include:

See also

Configuring the Sphinx build, from the Technote package documentation.

With conf.py#

If technote.toml does not provide the configuration you need, you can customize the Sphinx build by adding additional lines of Python to your conf.py file. Any lines added to the conf.py file can override the configuration provided by Documenteer, or set new Sphinx configurations. The existing configurations provided by Documenteer are shown in Configuration source reference, below.

See also

Directly configuring Sphinx and extensions, from the Technote package documentation.

Intersphinx inventory cache settings#

Technotes prefetch their Intersphinx object inventories (objects.inv) from the Ook inventory cache service: Documenteer’s documenteer.ext.intersphinxcache extension downloads each one and points Sphinx at the local copy, so a technote build doesn’t depend on third-party site availability. A technote build therefore logs the same inventory prefetch summary a user guide does, and gets the same notice when Ook reports that one of its configured inventory URLs has permanently moved.

The Intersphinx projects a technote links to aren’t set here. They live in the [technote.sphinx.intersphinx.projects] table of technote.toml — which is also the table a permanent-redirect notice names when a URL you configure has moved.

The cache settings are a different matter. Guides configure them through the [sphinx.intersphinx.cache] table of a documenteer.toml file, but technotes don’t have that file, and Documenteer adds no keys to technote.toml, whose schema belongs to the Technote package rather than to Documenteer. conf.py is therefore the supported way to override these settings in a technote. Set any of them after the from documenteer.conf.technote import * line:

documenteer_intersphinx_cache_warn_on_permanent_redirect

Whether to report a permanently-moved inventory URL as a Sphinx warning rather than at the INFO log level. Default is False, so a warnings-as-errors (-W) technote build never fails because a third party moved an inventory. Set it to True if you’d rather your build fail than carry a stale inventory URL.

See warn_on_permanent_redirect for what the notice says and what escalating it does — including the documenteer.intersphinx_permanent_redirect warning subtype that silences a move you already know about, while keeping the warning for every other inventory.

documenteer_intersphinx_cache_use_service

Whether to prefetch inventories from the Ook inventory cache service. Default is True. Set it to False as an escape hatch so Intersphinx fetches every inventory directly from its origin site.

documenteer_intersphinx_cache_service_url

Base URL of the Ook API that hosts the inventory cache service. Default is "https://roundtable.lsst.cloud/ook".

documenteer_intersphinx_cache_disk_cache_ttl

How long, in seconds, a prefetched inventory on disk is reused before Documenteer revalidates it with the service. Default is 600 (10 minutes). Set it to 0 to disable that fast path so every build revalidates with the service.

For example, to make a moved inventory URL fail the technote’s build:

conf.py#
from documenteer.conf.technote import *  # noqa: F401, F403

documenteer_intersphinx_cache_warn_on_permanent_redirect = True

Note

Prefetching needs a bearer token for the Ook API, read from the OOK_TOKEN environment variable. Without it the extension is a complete no-op and stock Intersphinx behavior is unchanged, so the technote still builds — there’s simply no summary block in the log.

Configuration source reference#

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

import warnings
from contextlib import suppress
from pathlib import Path

from sphinx.deprecation import RemovedInNextVersionWarning
from technote.sphinxconf import *  # noqa: F403

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

from ._utils import (
    get_common_nitpick_ignore,
    get_common_nitpick_ignore_regex,
    get_technote_origin_base_url,
)

# Suppress warnings about deprecated features in future Sphinx versions.
# This is noise for users because Documenteer itself constrains the Sphinx
# version.
warnings.filterwarnings(
    "ignore",
    category=RemovedInNextVersionWarning,
)

with suppress(ValueError):
    # 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

with suppress(ValueError):
    # Remove myst-parser if added by technote.sphinxconf so we can
    # add myst-nb.
    extensions.remove("myst_parser")  # noqa: F405


# Add the GitHub bibfile cache extension before sphinxcontrib-bibtex so
# that it can add bibfiles to the sphinxcontrib-bibtex configuration.
extensions.extend(  # noqa: F405
    [
        "myst_nb",  # enables MyST markdown and Jupyter Notebook parsing
        "documenteer.ext.jira",
        "documenteer.ext.lsstdocushare",
        "documenteer.ext.mockcoderefs",
        "documenteer.ext.remotecodeblock",
        "documenteer.ext.bibtex",
        "documenteer.ext.githubbibcache",
        "sphinxcontrib.bibtex",
        "documenteer.ext.diagrams",
        "sphinxcontrib.mermaid",
        "sphinx_prompt",
        "sphinx_design",
        "sphinxcontrib.youtube",
        "sphinx_sitemap",
        "documenteer.ext.linkcheckservice",
        "documenteer.ext.intersphinxcache",
    ]
)

# The source file suffixes for .md and .ipynb are automatically managed by
# myst-nb.
source_suffix = {
    ".rst": "restructuredtext",
}

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

# Enable mermaid code fences as the Mermaid directive.
myst_fence_as_directive = ["mermaid"]

# Exclude non-index.ipynb Jupyter Notebooks
extend_excludes_for_non_index_source(exclude_patterns, "ipynb")  # noqa: F405
extend_excludes_for_non_index_source(exclude_patterns, "md")  # noqa: F405
extend_excludes_for_non_index_source(exclude_patterns, "rst")  # noqa: F405

# 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
# Automatically load local bibfiles in the root directory.
bibtex_bibfiles = [str(p) for p in Path.cwd().glob("*.bib")]

bibtex_default_style = "lsst_aa"
bibtex_reference_style = "author_year"

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

# Ook link-check service settings for documenteer.ext.linkcheckservice.
# Only the technote-derived settings are set here; the others keep the
# defaults registered by the extension. All of them are overridable in
# the technote's conf.py after the ``from documenteer.conf.technote
# import *`` line (e.g. ``documenteer_linkcheck_use_service = False``
# restores Sphinx's built-in linkcheck builder).
_canonical_url = T.toml.technote.canonical_url  # noqa: F405
documenteer_linkcheck_origin_base_url = get_technote_origin_base_url(
    canonical_url=str(_canonical_url) if _canonical_url else None,
    technote_id=_id,
)
documenteer_linkcheck_default_branch_name = (
    T.toml.technote.github_default_branch  # noqa: F405
)

nitpick_ignore_regex.extend(get_common_nitpick_ignore_regex())  # noqa: F405
nitpick_ignore.extend(get_common_nitpick_ignore())  # noqa: F405

# Configure sitemap.xml
sitemap_url_scheme = "{link}"
sitemap_show_lastmod = True
sitemap_excludes = [
    # These auto-generated pages aren't relevant in technotes, which are
    # meant to be single-page documents.
    "search.html",
    "genindex.html",
    "py-modindex.html",
]

This page was last modified on .

https://documenteer.lsst.io/technotes/configuration.html