# 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. The best way to do this is in a Python virtual environment that’s layered on top of the EUPS Stack’s site-packages. This way it’s easy to delete Documenteer and its dependencies without affecting the Python packages that come with the EUPS Stack.

In a base working directory — not inside a repository directory — create the virtual environment and pip-install Documenteer through the requirements.txt file for pipelines_lsst_io:

python -m venv --system-site-packages --without-pip pyvenv
source pyvenv/bin/activate
curl https://bootstrap.pypa.io/get-pip.py | python
curl -O https://raw.githubusercontent.com/lsst/pipelines_lsst_io/master/requirements.txt
pyvenv/bin/pip install -r requirements.txt


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.

Tip

When you open a new terminal session, you can reactivate the Python virtual environment in the pyvenv directory by running:

source pyvenv/bin/activate


Do this after setting up the EUPS Stack.

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.

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


## Deactivating the virtual environment and cleaning up Documenteer¶

When you’re done, you can always deactivate the pyvenv virtual environment and even delete it.

To deactivate the virtual environment, run:

deactivate


To fully delete the pyvenv virtual environment, delete it:

rm -r pyvenv