Building the pipelines.lsst.io site locally¶
You can build the full pipelines.lsst.io site on your own computer. Although this is slightly more complicated than building documentation for a single package, it’s the best way to ensure that cross-package links work properly.
Alternatively, you can also build and publish a development version of pipelines.lsst.io with the sqre/infrastructure/documenteer Jenkins CI job. That Jenkins job only accepts development branches of the pipelines_lsst_io repository — not development branches of packages. The method described on this page is currently the only way to build documentation for development branches of packages with the full LSST Science Pipelines stack.
Before starting, you’ll need a working
This installation needs to be a recent daily or weekly build so that any in-development packages will compile with the Stack. Working from the tip of the
master branch is the norm for LSST software development.
Clone and set up the pipelines_lsst_io repository¶
pipelines_lsst_io is the main documentation repository for the pipelines.lsst.io site. It contains project-wide content, like installation guides and release notes, and also provides the structure for gathering documentation content from individual packages in the LSST Science Pipelines package stack.
Clone the repository:
git clone https://github.com/lsst/pipelines_lsst_io
Then set up the pipelines_lsst_io package with EUPS:
setup -r pipelines_lsst_io
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.
python -m venv --system-site-packages --without-pip pyvenv source pyvenv/bin/activate curl https://bootstrap.pypa.io/get-pip.py | python pyvenv/bin/pip install -r pipelines_lsst_io/requirements.txt
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.
Building the pipelines_lsst_io site¶
Move into the
The built site is located in the
Cleaning up built documentation¶
You can clean up the built documentation and intermediate artifacts by running:
Cleaning up the build is useful if you need to force a rebuild of the documentation either because a previous build failed, or a docstring changed. Sphinx does not automatically invalidate its cache when docstrings change.
Adding a locally-developed package to the pipelines_lsst_io build¶
The pipelines_lsst_io build works by symlinking the doc/ directory contents of packages that are set up by EUPS. This means that by setting up a package, you can add it to your local pipelines_lsst_io build.
For this tutorial, you’ll use the pipe_base package as an example.
First, move out of the
pipelines_lsst_io directory and clone pipe_base:
cd .. git clone https://github.com/lsst/pipe_base
Then set up and compile pipe_base, while keeping other packages set up (the
cd pipe_base setup -k -r . scons
Then clean and build the pipelines_lsst_io documentation:
stack-docs -d ../pipelines_lsst_io clean stack-docs -d ../pipelines_lsst_io build
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, change to the directory containing
pyvenv and delete it:
rm -r pyvenv
Alternative ways to build documentation:
- Building single-package documentation locally
- Building pipelines.lsst.io with Jenkins CI