Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
99 lines (68 sloc) 6.57 KB

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 :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 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 :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.

Package documentation

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:

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.

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 :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.

Note

Where information in the Developer Guide and DMTN-030 conflict, follow the guidelines in the Developer Guide. DMTN-030 is a design document, whereas the Developer Guide contains practical, up-to-date information on how to implement the design.