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:
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:
Adding additional Sphinx extensions (see Sphinx extensions in technotes)
Adding projects for Intersphinx ([technote.sphinx.intersphinx])
Setting the exemptions for the link check ([technote.sphinx.linkcheck])
Setting the “nitpick” mode and exemptions for warning on build issues
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."""
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["editions_url"] = ( # noqa: F405
f"https://{_id.lower()}.lsst.io/v/"
)