Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.


Keywords
lsst, lsst-doc-engineering
License
MIT
Install
pip install documenteer==0.6.12

Documentation

Documentation PyPI MIT license Uses wheel For Python 3.7+ CI Service

Documenteer

Documenteer provides tools, extensions, and configurations for Rubin Observatory's Sphinx documentation projects, include technotes and stacks (such as the LSST Science Pipelines).

For more information about Documenteer, see the documentation at https://documenteer.lsst.io.

Browse the lsst-doc-engineering GitHub topic for more Rubin Observatory documentation engineering projects.

Quick installation:

For technical note projects:

pip install "documenteer[technote]"

For the stack projects (such as the LSST Science Pipelines):

pip install "documenteer[pipelines]"

Features

Configurations

Documenteer includes preset configurations for common LSST DM Sphinx projects. By using Documenteer, you can also ensure that Sphinx extensions required by these configurations are installed.

From the conf.py for technotes:

from documenteer.conf.technote import *

From the conf.py for a stack package:

from documenteer.conf.pipelinespkg import *

project = "example"
html_theme_options['logotext'] = project
html_title = project
html_short_title = project

From the conf.py for the LSST Science Pipelines documentation:

from documenteer.conf.pipelines import *

Command-line tools

  • package-docs builds documentation for individual packages in the LSST Science Pipelines
  • stack-docs builds documentation for entire Stacks, such as the LSST Science Pipelines
  • refresh-lsst-bib maintains LSST's common BibTeX files in individual technote repositories

Sphinx extensions

  • Roles for linking to LSST documents and Jira tickets
  • The remote-code-block directive
  • The module-toctree and package-toctree directives for the LSST Science Pipelines documentation
  • Extensions for documenting LSST Science Pipelines tasks
  • Support for LSST BibTeX files with sphinxcontrib-bibtex.