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.

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