Overview of the Stack documentation system¶

This overview helps developers understand the system that builds and publishes user documentation for LSST’s EUPS-managed Stack products. This page includes links to further documentation on how to contribute to the documentation.

pipelines.lsst.io is the documentation site for the lsst_distrib Stack (the LSST Science Pipelines).

Main documentation repository¶

Each Stack documentation site has a corresponding main documentation repository. For the pipelines.lsst.io site, the main documentation repository is pipelines_lsst_io.

The role of the main documentation repository is to set up the structure of the Sphinx documentation project. The main documentation repository provides high-level content, such as installation guides, introductory guides and tutorials, and release notes.

Besides its own content, the main documentation repository also creates links into content from packages’s doc/ directories (and see How to add a package to pipelines.lsst.io). The primary examples are the Modules and Packages sections of the pipelines_lsst_io homepage that link to module homepages and package homepages, respectively. These sections are automatically populated by module-toctree and package-toctree, which are specializations of Sphinx’s own toctree directive. In other words, the Modules and Packages sections are where package documentation content is added to the main content hierarchy of the pipelines_lsst_io Sphinx project.

In addition to the Modules and Packages sections, the plan for the pipelines_lsst_io repository is to also have sections called Processing and Frameworks. The Processing section will collect Task documentation and tutorials around specific data processing contexts (single-frame processing, for example). The Frameworks section will gather content from modules and packages around different API themes, called frameworks, to help make the package-based codebase easier to rationalize and navigate. For example, one framework would be the “Task framework,” consisting of APIs from pipe_base, pipe_supertask, and pex_config. You can think of the Processing and Frameworks sections as content playlists that organize information across multiple packages along topical lines, outside the strict Modules and Packages hierarchy.

Package documentation¶

Packages include their own documentation content in their doc/ directories. By maintaining documentation in the same repository as the code content, it is easier to keep documentation up-to-date with the implementation.

Documentation for packages is split into two type types of directories, depending on the nature of the package:

Packages that provide one or more Python modules have corresponding module documentation directories.
Packages that do not provide Python modules have package documentation directories that document the contents of the package.

Content within a package’s doc/ directory is written in reStructuredText. Each page conforms to a topic type (a template, essentially) that defines the style and structure of the content (see Topic types for package documentation). By maintaining consistent information structures, documentation content is both easier to write and easier for readers to use and navigate.

The documentation build process¶

Documenteer is the Python package that provides tooling for LSST DM’s Sphinx-based documentation projects, including Stack user guides such as pipelines.lsst.io. See Overview of the pipelines.lsst.io build system in the Documenteer documentation for an overview of how the documentation is built.

Documentation deployment¶

Stack documentation is deployed to the web with LSST the Docs (SQR-006). The homepage for the LSST Science Pipelines documentation is pipelines.lsst.io.

LSST the Docs hosts multiple editions of documentation that reflect different versions of the project, including releases and development versions. Jenkins CI, through different release pipelines and the standalone sqre/infrastructure/documenteer Job, automatically builds and publishes documentation editions for each major, weekly, and daily release. We also intend to support development branches, though this hasn’t been built into the stack-os-matrix job yet.

The main documentation edition, which is published at https://pipelines.lsst.io without a /v/ path prefix, is the most recent major version of the LSST Science Pipelines.