add-a-package-to-pipelines-lsst-io.rst

How to add a package to pipelines.lsst.io

The pipelines.lsst.io documentation site incorporates content from the doc/ directories <layout-of-doc-directory> 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. add-to-pipelines-lsst-io-prep
2. add-to-pipelines-lsst-io-eups-table
3. add-to-pipelines-lsst-io-eups-test
4. add-to-pipelines-lsst-io-eups-merge

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 </work/flow>).
3. Add files to the package’s doc/ directory. See layout-of-doc-directory for details.

At this stage, you can build the documentation content for this package alone. See Building single-package documentation locally <building-single-package-docs> 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-pipelines-lsst-io-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 local-pipelines-lsst-io-build-package-setup 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 </work/flow>.

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