How to add a package to pipelines.lsst.io

The pipelines.lsst.io documentation site incorporates content from the doc/ directories of individual LSST Science Pipelines packages. This page describes how to add a package’s documentation content to the pipelines.lsst.io documentation site. The steps are:

  1. Prepare the package’s doc directory
  2. Add the package to pipelines_lsst_io’s EUPS table file
  3. Test the build
  4. Review and merge the branches

Prepare the package’s doc directory

The first step is to populate the package’s doc/ directory with the boilerplate files:

  1. Clone the package.
  2. Check out a ticket branch for development (following the usual workflow).
  3. Add files to the package’s doc/ directory. See Layout of the doc/ directory for details.

At this stage, you can build the documentation content for this package alone. See Building single-package documentation locally for directions.

Add the package to pipelines_lsst_io’s EUPS table file

The next step is to integrate that package’s documentation with the main documentation repository, pipelines_lsst_io:

  1. Clone the pipelines_lsst_io repository.
  2. Check out a ticket branch for development (use the same ticket as for setting up the package’s doc/ directory).
  3. Add the name of your package to the ups/pipelines_lsst_io.table file.

The combination of having a populated doc/ directory in your package and having that package set up by pipelines_lsst_io ensures that the package and any of its Python modules are listed on the homepage generated by pipelines_lsst_io.

Test the build

At this stage, you can locally build the pipelines.lsst.io site with your package’s content included. The page Building the pipelines.lsst.io site locally describes how to do this.

After you set up pipelines_lsst_io with EUPS, make sure that you also follow the steps in the section Adding a locally-developed package to the pipelines_lsst_io build to set up your package. Even though you’ve added your package to pipelines_lsst_io’s EUPS table file, you need to ensure that it’s your local copy that’s being set up, not the copy installed with your base lsst_distrib (or equivalent) installation.

Review and merge the branches

The last step is to merge the branches in both the package and pipelines_lsst_io repositories. In general, this should be done using DM’s regular review and merging workflow.

Merge the package’s branch first, followed by the branch for pipelines_lsst_io.