Documenteer¶
Sphinx extensions, configurations, and tooling for Rubin Observatory documentation projects.
Documenteer is developed on GitHub at lsst-sqre/documenteer. Find other versions of the documentation at https://documenteer.lsst.io/v
Installation¶
The core package provides Documenteer’s Sphinx extensions:
pip install documenteer
To use Documenteer’s configurations for specific Rubin documentation use cases, you’ll need to install Documenteer with specific “extras” to bring in the necessary dependencies.
For Rubin user guide projects:
pip install "documenteer[guide]"
For technote projects:
pip install "documenteer[technote]"
Documenteer is available from conda-forge for Conda users. First, enable the conda-forge channel:
conda config --add channels conda-forge
conda config --set channel_priority strict
The core package provides Documenteer’s Sphinx extensions:
conda install documenteer
To use Documenteer’s configurations for specific Rubin documentation use cases, you’ll need to install Documenteer with specific “extras” to bring in the necessary dependencies.
To install Documenteer for technote projects:
conda-install lsst-documenteer-technote
Project guides¶
Documenteer provides centralized Sphinx configuration and support for Rubin Observatory documentation projects. This section describes how to use Documenteer for specific types of projects, from single-page technical notes to user guides.
- Rubin user guides
- Rubin user guide features
- Setting up the Documenteer configuration for Rubin user guides
- Organizing content in a Rubin user guide
- Configuring Python projects in documenteer.toml
- Embedding a Redoc subsite for OpenAPI (HTTP API) documentation
- Using the rst epilog for common links and substitutions
- Redirecting pages when reorganizing content
- Extending conf.py directly
- Diagrams as code
- Badges
- Tab sets
- Embedded videos
- Using Markdown syntax in Rubin Observatory documentation
- Including Jupyter notebooks in documentation
- documenteer.toml reference
- The documenteer.conf.guide configuration preset
- Technical notes
- Start a new technote
- Edit a technote on your own computer
- Editing a technote with the GitHub web UI
- How your technote gets published to the web
- Migrate legacy reStructuredText/Sphinx technical notes
- Maintaining author metadata
- Describing the document status (draft, deprecated, or stable)
- Accommodating wide content (tables, code blocks, and images)
- Configuring the Sphinx build
- Sphinx extensions in technotes
Sphinx extensions¶
Documenteer provides several Sphinx extensions. These extensions are designed for Rubin Observatory documentation projects, but are may be generally useful: