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.

documenteer.ext.diagrams

This extension renders Diagrams (diagrams as code) into architectural diagrams. It is particularly useful for describing Kubernetes application deployments.

By default, diagrams are rendered as PNG images. To render scalable SVG output instead, set the diagrams_output_format configuration value (to "svg"; the default is "png") in your conf.py, the same way you would set mermaid_version:

conf.py

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

diagrams_output_format = "svg"

SVG output is self-contained because the provider node icons are embedded as base64 data: URIs. LaTeX/PDF builds always use PNG, since pdflatex cannot embed SVG images.

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):

1. 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
   

2. 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.

3. 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"