Sphinx extensions in technotes#

Technotes include Sphinx extensions that provide additional features, like diagrams-as-code. This page explains what extensions are included by default in Rubin technotes, and how to add additional extensions to your own technote as needed.

Default extensions#

These extensions are included and pre-configured in all technotes:

documenteer.ext.jira: This extension provides roles for linking to Jira issues.
documenteer.ext.lsstdocushare: This extension provides roles for linking to Rubin Observatory documents based on their handle.
documenteer.ext.remotecodeblock: This extension allows you to include a literal code block where the source for that code block is available at an web URL.
documenteer.ext.bibtex: This extension works with the sphinxcontrib-bibtex extension to handle the BibTeX entires in lsst/lsst-texmf.
documenteer.ext.githubbibcache: This extension automatically downloads and caches the BibTeX files from lsst/lsst-texmf, for use with the sphinxcontrib-bibtex extension.
myst_parser: This extension allows you to use the MyST markup language (i.e., Markdown) in your technote.
sphinx.ext.intersphinx: This extension allows you to link to other Sphinx projects, including other Rubin technotes and user guides and many open-source projects like Astropy and Numpy.
sphinxcontrib-bibtex: This extension allow you to include a BibTeX-based bibliography in your technote.
sphinx-prompt: Sphinx-prompt lets you add a prompt to code blocks. This is useful for showing what a user might type at an interactive terminal.
sphinxcontrib-mermaid: Mermaid is a diagrams-as-code tool that allows you to create flowcharts, sequence diagrams, entity relationship diagrams, and more. See the Mermaid documentation for more information, and see the sphinxcontrib-mermaid documentation for Sphinx-specific usage.
sphinx-diagrams: The Diagrams extension allows you to make architectural diagrams from code. This extension is particularly useful for describing Kubernetes application deployments.

Adding additional extensions#

If you know of a Sphinx extension that you would like to use with your technote, you can add it yourself. Here are the steps, using sphinxcontrib-mermaid as an example (this is already included in all technotes):

Add the extension’s Python package to requirements.txt in the technote’s repository. This is the extension’s PyPI package name, since technotes use pip to install build dependencies.
requirements.txt#
```
documenteer[technote]
sphinxcontrib-mermaid
```
Add the extension to the technote.sphinx.extensions array in technote.toml. Either append to the existing array, or create a new array if it doesn’t exist in the TOML file yet.
technote.toml#
```
[technote.sphinx]
extensions = ["sphinxcontrib.mermaid"]
```
Tip

The extension name is the Python package name, not the PyPI package name. Look at the extension’s installation documentation for the extensions variable to find the Python package name.

Note

User-defined extensions are always installed in addition to the default extensions. You don’t need to repeat the default extensions here.

If the extension has configurations, you can set those in the conf.py file.

conf.py#

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

# -- Options for sphinxcontrib-mermaid -------------------------------------
mermaid_version = "8.9.2"