Layout of the doc/ directory¶

This page describes the layout of doc/ directories in packages. By following these guidelines, the documentation content of individual packages can successfully integrate with the build of pipelines.lsst.io.

The stack_package template¶

Use the stack_package template, and its examples, as references for implementing the doc/ directory of your package. This page will refer to those templates frequently.

The doc/ directory structure of the example package looks like this:

doc
├── SConscript
├── conf.py
├── doxygen.conf.in
├── index.rst
├── lsst.example
│   ├── index.rst
│   │── scripts
│   └── tasks
└── manifest.yaml

The doc/manifest.yaml file¶

This YAML file describes the content of the package’s doc/ directory. The build process uses the doc/manifest.yaml file to symlink documentation content from packages into the main documentation repository, pipelines_lsst_io.

The doc/manifest.yaml file for a package named example looks like this:

# Documentation manifest.

# List of names of Python modules in this package.
# For each module there is a corresponding module doc subdirectory.
modules:
  - "lsst.example"

# Name of the static content directories (subdirectories of `_static`).
# Static content directories are usually named after the package.
# Most packages do not need a static content directory (leave commented out).
# statics:
#   - "_static/example"

modules field¶

The modules field is a list of the public Python modules that the package provides. For most packages, as is the case for the example above, the package provides just one public Python module (lsst.example, for example).

Each item in the modules list corresponds to a module documentation directory.

Note

“Modules” here means the major public modules provided by a package, created by an __init__.py files. Most packages provide just one major namespace that a Python user can import.

For example, the log package provides the lsst.log namespace.

Some packages provides several major public modules. For example, the afw package provides lsst.afw.cameraGeom, lsst.afw.coord, lsst.afw.detection, and so on. The lsst.afw module, on its own, isn’t used. For example, afw’s manifest.yaml file looks like this:

# Documentation manifest.

# List of names of Python modules in this package.
# For each module there is a corresponding module doc subdirectory.
modules:
  - "lsst.afw.cameraGeom"
  - "lsst.afw.coord"
  - "lsst.afw.detection"
  - "lsst.afw.display"
  - "lsst.afw.fits"
  - "lsst.afw.formatters"
  - "lsst.afw.geom"
  - "lsst.afw.image"
  - "lsst.afw.math"
  - "lsst.afw.table"
  - "lsst.afw.typehandling"

statics field¶

The statics field lists any _static directories included in the package’s doc/ directory. _static directories are a place to include content that’s shipped with the HTML site, but are otherwise unprocessed by Sphinx.

Packages don’t need _static directories, so this field can be commented out.

package field¶

Some packages don’t provide Python modules, and thus don’t have module documentation directories. Instead, these packages are documented with a single package documentation directory.

To declare a package documentation directory, add a package field to manifest.yaml. The package field must match the package’s EUPS name, which also corresponds to the name of the package documentation directory.

This is an example manifest.yaml for the example_dataonly package:

# Documentation manifest.

# Package documentation directory (named after the package itself).
# Only include a package documentation directory if package does not provide
# any modules.
package: "example_dataonly"

# Name of the static content directories (subdirectories of `_static`).
# Static content directories are usually named after the package.
# Most packages do not need a static content directory (leave commented out).
# statics:
#   - "_static/example_dataonly"

The doc/conf.py file¶

The doc/conf.py file provides Sphinx configurations during a single-package build. The doc/conf.py file for a packaged named example looks like this:

"""Sphinx configuration file for an LSST stack package.

This configuration only affects single-package Sphinx documentation builds.
For more information, see:
https://developer.lsst.io/stack/building-single-package-docs.html
"""

from documenteer.conf.pipelinespkg import *


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

Don’t add additional customizations to the package’s doc/conf.py file since it isn’t used during the build of pipelines.lsst.io (only the doc/conf.py of the pipelines_lsst_io package is used in that case).

The doc/.gitignore file¶

The doc/.gitignore file ensures that documentation build products don’t get accidentally checked into the package’s Git repository. The file looks like this:

# Doxygen products
html
xml
*.tag
*.inc
doxygen.conf

# Sphinx products
_build
py-api

The doc/index.rst file¶

The doc/index.rst file is the development homepage for the package. This page doesn’t appear in pipelines.lsst.io. Instead, it’s a temporary stand-in for pipelines_lsst_io’s index.rst file during single-package documentation builds that links to the package and module homepages described in doc/manifest.yaml.

The doc/index.rst file for an example package looks like this:

#############################
example documentation preview
#############################

.. This page is for local development only. It isn't published to pipelines.lsst.io.

.. Link the index pages of package and module documentation directions (listed in manifest.yaml).

.. toctree::
   :maxdepth: 1

   lsst.example/index

Customize the title and the entries in the toctree directive for your own package.

The doc/doxygen.conf.in file¶

If your package has C++ code, it needs to have Doxygen run on it. Add this empty file called doc/doxygen.conf.in.

The doc/SConscript file¶

If your package has C++ code, it needs to have Doxygen run on it. Add this standardized doc/SConcript file:

# -*- python -*-
from lsst.sconsUtils import scripts
scripts.BasicSConscript.doc()

Module documentation directories¶

doc/ directories contain a module documentation directory for each major public Python namespace provided by the package. These directories correspond to the modules listed in the modules field in the manifest.yaml file. Each module documentation directory provides a place to document the corresponding Python and C++ APIs.

The index.rst file contained in this directory follows the module topic type.

There are two standard subdirectories that a module documentation directory may have:

tasks/: For task and config topic pages.
scripts/: For script topic (or Argparse-based script topic type) pages.

Package documentation directory¶

This directory is only present for packages that do not have module documentation directories. In such cases, the package documentation directory provides a place to document the EUPS package itself. The index.rst file in this directory (see Package homepage topic type) provides links to the package’s GitHub repo and Jira component, for example.

The package documentation directory is a subdirectory of doc/ that is named after the EUPS package itself. For the package called example_dataonly, this directory is doc/example_dataonly. This directory corresponds to the package field in the doc/manifest.yaml file.

For a full example, see the example_dataonly example of the stack_package template.

Remember, most packages will not have a package documentation directory.

_static/ directory¶

The “static” directory is a place to put files that are included in the HTML deployment, but are not otherwise processed by Sphinx. Most packages don’t need the static directory at all. Static files, like PDFs and small data files, can just be included alongside the rst files in the module and package documentation directories.

Note

In early development, the doc/_static directory was required. This is no longer the case.

If a package does need a static directory, any content should be put in a subdirectory of doc/_static that is named after the package. For example, if the package name is afw, the static directory should be doc/_static/afw. At build time, it’s the doc/_static/afw directory that will be linked into the main documentation repository.

When linking to content in the _static directory, use an absolute URL, starting with /. For example:

:download:`/_static/afw/document.pdf`