Documenteer

Sphinx extensions, configurations, and tooling for Rubin Observatory documentation projects.

This documentation is for version 0.7.2. Find docs for other versions. Documenteer is developed on GitHub at lsst-sqre/documenteer.

Installation

pip

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]"

For LSST Science Pipelines projects and other EUPS stacks:

pip install "documenteer[pipelines]"

See Installing Documenteer for pipelines.lsst.io for more information.

conda

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

To install Documenteer for LSST Stack projects (such as https://pipelines.lsst.io and EUPS packages):

conda-install lsst-documenteer-pipelines

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, to LSST Science Pipelines package documentation.

• 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
  • Using the rst epilog for common links and substitutions
  • Extending conf.py directly
  • Diagrams as code
  • Badges
  • Tab sets
  • documenteer.toml reference
  • The documenteer.conf.guide configuration preset
• Technical notes
  • Sphinx configuration for technotes
  • Maintaining common BibTeX files with refresh-lsst-bib
• Science Pipelines
  • Installing Documenteer for pipelines.lsst.io
  • Overview of the pipelines.lsst.io build system
  • stack-docs command-line app
  • package-docs command-line app
  • Sphinx configuration for stacks and packages
  • Cross-linking the Doxygen-built C++ API reference with the lsstcc role

Sphinx extensions

Documenteer provides several Sphinx extensions. These extensions are designed for Rubin Observatory documentation projects, but are may be generally useful:

• Sphinx extensions
  • Sphinx extensions for the LSST Science Pipelines task framework
  • The autocppapi extension for listing Doxylink C++ APIs through Doxylink
  • Jira reference roles
  • LSST document reference roles
  • The remote code block extension
  • Package toctree extension for LSST Stack documentation
  • BibTeX style extension for LSST
  • The autodocreset extension for resetting automodapi’s autodoc enhancements

Developer guide

• Development
  • Development guide
  • Release procedure
  • Python API reference