Building single-package documentation locally

While developing a package and its documentation, you’ll probably want to preview what the documentation looks like when built. The quickest way to do this is with a single-package documentation build.

Keep in mind that a single-package documentation build may have many broken links because package documentation is meant to be built in the context of the package stack. To do a full-stack documentation build, see either:

Nevertheless, a single-package build is useful for checking formatting and proof-reading your work. This page describes how to run a single-package documentation build, using pipe_base as the example.

Prerequisites

Before starting this tutorial, you’ll need a working lsst_distrib installation. This installation should already be set up with a command like setup lsst_distrib.

This installation needs to be a recent daily or weekly build since you’ll be compiling the pipe_base repository from its master branch. Working from the tip of the master branch is the norm for LSST software development.

Install Documenteer, the documentation tooling

Documenteer provides tooling to build pipelines.lsst.io. Since it’s a PyPI-distributed Python package, you need to install it separately from the EUPS Stack. In a base working directory — not inside a repository directory — get the requirements.txt file for pipelines_lsst_io and install it:

curl -O https://raw.githubusercontent.com/lsst/pipelines_lsst_io/master/requirements.txt
pip install -r requirements.txt

Do this after setting up the EUPS Stack with a command like setup lsst_distrib.

If it is not already present in your environment, you may also want to install the graphviz package to enable generation of diagrams:

conda install graphviz

Note

On a shared resource, like lsst-dev, you will need to use a --user flag with pip install.

Note

By using the requirements.txt file in the pipelines_lsst_io repository, you can ensure you’re using the same version of Documenteer and its dependencies as in the CI builds of pipelines.lsst.io.

Downloading and setting up a package

You need to clone and build the package locally. In this example, you’ll be cloning and building pipe_base:

git clone https://github.com/lsst/pipe_base
cd pipe_base
setup -k -r .
scons

Note

If you’re actively developing a package, it’s likely that you’ve already cloned and built that package.

Building the package’s documentation

You can build the package’s documentation by running:

package-docs build

The built HTML is located, relative to the pipe_base directory, at doc/_build/html.

Note

The page at doc/_build/html/index.html is the homepage for single-package builds. It never appears in the pipelines.lsst.io site build but does link to all the package and module documentation directories listed in the package’s doc/manifest.yaml file.

See Documenteer’s documentation for more information about the package-docs command.

Deleting built documentation

Since Sphinx only builds files that have changed, and may not notice updated docstrings, you may need to delete the built documentation to force a clean rebuild. You can delete this built documentation by running:

package-docs clean