Rubin user guide features#
Documenteer provides a configuration preset for Rubin Observatory documentation sites built with Sphinx. This page provides an overview of the preset’s features.
If you want to get started using the configuration preset right away, see Setting up the Documenteer configuration for Rubin user guides.
Based on the PyData Sphinx Theme#
The base theme for Rubin user guides is PyData Sphinx Theme, a responsive design built around a three-pane layout with both light and dark color pallets. The Rubin user guide preset brands and configures the PyData theme, so that colors, logos, typefaces, and other design features are ready to go. For advice on how to structure your user guide’s content to work with the PyData Sphinx Theme’s navigation structure, see Organizing content in a Rubin user guide.
Besides the design features of PyData Sphinx Theme itself, the Rubin user guide preset also includes the Sphinx Design extension, which provides useful design features like tab sets and badges. See the Sphinx Design docs and the Design features pages in these docs for ideas.
Configuration with documenteer.toml#
The Rubin user guide preset is configurable through a TOML file, documenteer.toml, which reduces the amount of overriding necessary in the standard Sphinx conf.py file.
See Setting up the Documenteer configuration for Rubin user guides to get started.
Python projects that use the standard pyproject.toml metadata file for packaging benefit from automatic metadata introspection.
See Configuring Python projects in documenteer.toml and Advanced configuration pages for details.
Markdown support#
Rubin user guides can be written in Markdown, in addition to reStructuredText, thanks to the MyST extension. Through MyST, reStructuredText/Sphinx directives and roles are available as a layer on top of standard Markdown syntax. See the MyST documentation for more details on how to use reStructuredText features from Markdown.
Diagrams as code#
Support for Mermaid is built in, enabling you to add standard technical diagrams with restoring to graphics editors or binary files For infrastructure diagrams, we recommend using Diagrams, which you can easily install and configure.
See Diagrams as code for more information.
Python APIs with automodapi and autodoc#
The Rubin user guide preset configures a suite of Sphinx extensions for generating Python reference documentation from docstrings: