Building pipelines.lsst.io with Jenkins (sqre/infra/documenteer)¶
pipelines.lsst.io is automatically built and deployed for each
You don’t manually build and update the website when you contribute to the pipelines_lsst_io documentation repository.
You can, however, preview a development branch of the pipelines_lsst_io repository by manually running the sqre/infra/documenteer Jenkins CI job. Since pipelines.lsst.io is published through LSST the Docs, builds for development branches appear as new editions from the pipelines.lsst.io/v version dashboard.
You can’t use this Jenkins CI job to test development branches of packages with the pipelines.lsst.io site build. This Jenkins CI job always uses packages corresponding to a released EUPS tag (such as a daily, weekly, or stable release). Only the branch of the pipelines_lsst_io repository can be modified.
If you need to build and test your package’s documentation, you can do so locally with these methods:
This section describes how most contributors will use the sqre/infra/documenteer Jenkins job: to preview a ticket branch of the pipelines_lsst_io repository.
In this example, the ticket branch is called
First, go to the sqre/infra/documenteer job’s page, then click the Run button. Then fill in the fields as shown in the following screenshot.
Here is more detail about each field:
- EUPS distrib tag name:
d_latestEUPS tag automatically aliases the most recent EUPS daily build tag. Using
d_latesthere is useful because when you’re writing new content for the pipelines_lsst_io repository, you often want to pair it with the latest version of the
- LTD edition slug:
LSST the Docs uses this field to build the “slug,” or
/v/<slug>/URL path prefix, for alternative documentation editions. In this case, you want to use the name of the branch in the pipelines_lsst_io repository to identify the edition as corresponding to the
tickets/DM-16182development branch. LSST the Docs automatically transforms this value into the
- github repo slug:
Always use this value.
- git repo ref:
This field determines which branch of the GitHub repository (pipelines_lsst_io) to clone and build. Use the development ticket branch,
Leave this field checked so that the built documentation site is published to the web. You can find the edition at https://pipelines.lsst.io/v.
This section has more information about each configuration field.
EUPS distrib tag name¶
This is the EUPS tag of the
lsst_distrib Stack that populates the package and module documentation that’s building alongside the main pipelines_lsst_io repository.
You can set this field to a major release, weekly release, or a daily release.
Major release example:
Weekly release example:
Daily release example:
You can also use these aliases:
Latest weekly tag:
Latest daily tag:
This field means that you can only build documentation for tags of Stack packages that have been released by Jenkins CI.
LTD edition slug¶
Set this field to either a Git ref or an EUPS tag.
LSST the Docs uses this information to populate the version slug of the edition (the part of the URL directly after
Follow these guidelines:
Example: you have a branch called
tickets/DM-16182in the pipelines_lsst_io repository. Set this field to
tickets/DM-16182. LSST the Docs automatically transforms this value into the
/v/DM-16182/edition path prefix.
If you are rebuilding documentation for a released version of the
lsst_distribpackage, set this field to the name of the corresponding EUPS tag.
Example: you are rebuilding documentation for the
d_2018_10_29EUPS tag of
lsst_distrib. Set this field to
Note: you generally will never do this as developer contributing new content.
github repo slug¶
This is the GitHub repository slug for the main documentation repository.
This should always be
git repo ref¶
If you are building an EUPS release, set this field to the name of the Git branch, tag or commit SHA corresponding to the EUPS tag.
Explicit name of release docker image including tag¶
Leave this field blank.
Run the Job¶
Ensure that the Publish option is checked so that the build site is published as a development branch on pipelines.lsst.io.
Viewing the results¶
Once the job successfully finishes, open pipelines.lsst.io/v and find the corresponding edition that you just built.