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
└── 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.

# Name of this package
# Also the name of the package documentation subdirectory.
package: "afw"

# 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"

# Name of the static content directories (subdirectories of `_static`).
# Static content directories are usually named after the package.
statics:
  - "_static/afw"

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 should look like this example:

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

This configuration only affects single-package Sphinx documentation builds.
"""

from documenteer.sphinxconfig.stackconf import build_package_configs
import lsst.example


_g = globals()
_g.update(build_package_configs(
    project_name='example',
    version=lsst.example.version.__version__))

Fill in the project_name and version keyword arguments as appropriate.

Be careful not to add customizations to this conf.py file since they won’t be used during the build of pipelines.lsst.io (only the 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.

See the Module homepage topic type for details on the index.rst file contained in each module documentation directory.

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`