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 -k -r pipelines_lsst_io
Install Documenteer, the documentation tooling¶
cd pipelines_lsst_io pip install -r requirements.txt
Do this after running the setup command.
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
On a shared resource, you will need to use a
--user flag with pip install.
Building the pipelines_lsst_io site¶
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
Alternative ways to build documentation:
- Building single-package documentation locally
- Building pipelines.lsst.io with Jenkins CI