Documenting Stack Packages

Note

This is a preview documentation format specification. Software documentation should currently be written in the format described at https://confluence.lsstcorp.org/display/LDMDG/Documentation+Standards

The LSST Stack is an aggregation of packages contained in individual git repositories (see github.com/lsst). This page explains how to organize and write package documentation that can be integrated into software documentation, such as the LSST Science Pipelines docs. In separate pages we cover writing docstrings for Python and C++, respectively. We use reStructuredText to markup our documentation; see our reStructuredText Style Guide for more information on this markup language.

Layout of a Package: The Doc Perspective

From a perspective of documentation, the repository of every Stack package is laid out as follows:

package_name/
\ _ ... source files
 |_ README.rst
 |_ LICENSE
 |_ COPYRIGHT
 |_ CONTRIBUTING.rst
 |_ docs/
    \_ index.rst

In the follow sections we describe how to produce the content for each of these documentation files and directories.

The Package’s User Guide in docs/

The heart of a Stack package’s documentation are files in the docs/ directory [1]. This content is ingested by Sphinx, our documentation build tool, to publish user guides for each package. In the following section we describe how to write the main documentation file, docs/index.rst.

[1]LSST’s previous Doxygen-based documentation platform placed its content in the doc/ directory. Thus the Sphinx and Doxygen documentation can coexist during the documentation transition.

Template for a Package’s index.rst

Consistent documentation patterns make it easier for users to read the Docs. For every package’s user guide, we strongly recommend using the following sections:

  1. “Introduction”
  2. “Getting Started”
  3. “Tutorials” (optional)
  4. “Using package_name”
  5. Discretionary sections
  6. “Python Reference”
  7. “C++ Reference”

To implement this pattern, every package’s index.rst should follow this basic template:

.. _lsst-package-name:

###################
package_name - Slug
###################

.. _lsst-package-name-intro:

Introduction
============

Tell people what the package does (in a few paragraphs).
List features here.

.. _lsst-package-getting-started:

Getting Started
===============

A quick tutorial that covers the main functionality.
It should be *brief* (a laptop screen or two) and *shouldn't be exhaustive*.

.. _lsst-package-getting-started:

Using package_name
==================

A series of sections that cover API usage.

Subsections
-----------

Use sectioning liberally.

Other sections
==============

This is where you can put other types of content, such as more
detailed architectural descriptons for developers.

.. _lsst-package-name-py-ref:

Python Reference
================

API reference for Python developers.

.. _lsst-package-name-cpp-ref:

C++ Reference
=============

API reference for C++ developers

We recommend that the entirety of a package’s documentation be contained in a single index.rst file. This minimal pagination makes it easier for readers for use their browser’s search to find specific phrases.

In the following sections we expand on key concepts in writing a package’s user guide.

Sections

In keeping with Python community conventions and our style guide, we use the following section markup for different levels of headings:

  1. Page title: # with overline,
  2. Sections: =,
  3. Subsections: -,
  4. Subsubsections: ^,
  5. Paragraphs: ".

Section Labels

Although Sphinx can automatically provide section link targets, we recommend that you provide explicit link targets since they don’t change when headline text changes.

Section labels should be placed directly above the header and follow the syntax _label:. Note that hyphens should be used to separate words in a label; underscores are only used to prefix the label.

For package documentation, we recommend that you prefix section labels with the Python namespace, joined by hyphens (-). For example, the section label for the lsst.afw package should be:

.. _lsst-afw:

By convention, we use the following labels for standardized package sections

  • “Introduction:” lsst-package-name-intro
  • “Getting Started:” lsst-package-name-getting-started
  • “Using package_name:” lsst-package-name-using
  • “Python Reference:” lsst-package-name-py-ref
  • “C++ Reference:” lsst-package-name-cpp-ref

Titling the Package’s User Guide

We recommend the title for a package’s user guide follow the format

########################
lsst.package_name - Slug
########################

That is, the title should provide the Python namespace of the package first, followed by the ‘slug.’. The slug is merely a short phrase that elucidates the package’s role. For example,

################################
lsst.afw - Application Framework
################################

The ‘Introduction’ Section

The Introduction section should be an approachable summary of what the package does. Write the Introduction for users who have never used the package before, and need to decide quickly whether this is the package that can solve their problems or not. Including a bulleted feature list could be a good thing too, but don’t be long-winded.

The ‘Getting Started’ Section

The Getting Started section is a quick demo, with code that a user could paste into a Jupyter notebook and see something happen. This section isn’t meant to be a complete survey of the package’s functionality; it’s only meant to say hey there! you can actually use this thing.

The ‘Tutorials’ Section

This section can provide links to tutorials that use this package.

The ‘Using package_name’ Section

This section is the heart of the Package’s user guide. This section should be comprehensive and explain all the major functionality of the package. Code examples should be used liberally. We encourage you to divide the Using section into multiple, short, subsections to ensure it is skimable/navigable.

The ‘Python Reference’ Section

The Python Reference is generated automatically from the Python docstrings.

Todo

Explain how to setup autodoc directives

The ‘C++ Reference’ Section

The C++ Reference is generated automatically from the doxygen-formatted C++ code comments.

Todo

Explain how to setup the documentation directives

Acknowledgements

We credit the Astropy project for developing the Introduction - Getting Started - Using - API Reference pattern for package documentation.