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
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 :doc:`packages’s doc/ directories <layout-of-doc-directory>` (and see :doc:`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 :doc:`module homepages <module-homepage-topic-type>` and :doc:`package homepages <package-homepage-topic-type>`, respectively.
These sections are automatically populated by
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 :ref:`plan <stack-docs-system-further-reading>` 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.
Packages include their own documentation content in their :doc:`doc/ directories <layout-of-doc-directory>`. 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 :ref:`module documentation directories <docdir-module-doc-directories>`.
- Packages that do not provide Python modules have :ref:`package documentation directories <docdir-package-doc-directory>` that document the contents of the package.
Content within a package’s :doc:`doc/ directory <layout-of-doc-directory>` is written in :doc:`reStructuredText </restructuredtext/style>`. Each page conforms to a topic type (a template, essentially) that defines the style and structure of the content (see :doc:`package-documentation-topic-types`). 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 :ref:`documenteer:pipelines-build-overview` in the Documenteer documentation for an overview of how the documentation is built.
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 :doc:`stack-os-matrix <jenkins-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.
Further reading about the documentation architecture
DMTN-030 Science Pipelines Documentation Design describes the architecture for the Stack documentation system, and content design for the LSST Science Pipelines documentation in particular. See that technote to understand the design decisions behind the Stack documentation system.