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:
- Building the pipelines.lsst.io site locally
- Building pipelines.lsst.io with Jenkins (sqre/infrastructure/documenteer)
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.
Before starting this tutorial, you’ll need a working
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
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
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/tickets/DM-11216/requirements.txt pyvenv/bin/pip install -r requirements.txt
FIXME update branch after
tickets/DM-11216 is done.
When you open a new terminal session, you can reactivate the Python virtual environment in the
pyvenv directory by running:
Do this after setting up the EUPS Stack.
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
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:
The built HTML is located, relative to the
pipe_base directory, at
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:
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:
To fully delete the
pyvenv virtual environment, delete it:
rm -r pyvenv
Alternative ways to build documentation:
FIXME update links after
tickets/DM-14852 is done.