Documentation jobs

All documentation jobs are listed under the Docs view tab of Jenkins. A GitHub button in the left-side panel of the job window links to the code repository the job is building from (alternatively, the console output for the build will indicate where the changes are being fetched from).

More detail on how and where to edit OME documentation is available on the Editing the OME documentation page.

Job task OMERO 5.x series
Builds the latest OMERO documentation for publishing OMERO-DEV-latest-docs
Builds the OMERO documentation for review OMERO-DEV-merge-docs
Builds the auto-generated OMERO documentation OMERO-DEV-latest-docs-autogen
Builds the auto-generated OMERO documentation for review OMERO-DEV-merge-docs-autogen
Job task Bio-Formats 5.x series
Builds the latest Bio-Formats documentation for publishing BIOFORMATS-DEV-latest-docs
Builds the Bio-Formats documentation for review BIOFORMATS-DEV-merge-docs

The OME Model, OME help and OME Contributing documentation sets are independent of the current OMERO/Bio-Formats version.

Job task  
Build the latest OME Model documentation MODEL-latest-docs
Publish OME Contributing documentation CONTRIBUTING-latest-docs
Review OME Model documentation PRs MODEL-merge-docs
Review OME Contributing documentation PRs CONTRIBUTING-merge-docs
Review OME help documentation PRs OME-help-staging
Publish OME help documentation OME-help-release

Since OMERO.figure came under the management of the wider OME team, there are also builds to manage its GitHub pages website, which operate the same way as the help builds.

Job task  
Review PRs opened against the OME Website WWW-merge
Review PRs opened against the OMERO.figure website FIGURE-help-staging
Publish the OMERO.figure website FIGURE-help-staging
Review PRs opened against the OME help website OME-help-staging
Publish the OME help website OME-help-release

OME Files comprises OME Model, OME Files C++ and OME CMake Super-Build Sphinx manuals, which are taken from separate repositories but built and hosted as a bundle.

Job task  
Publish OME Files documentation OME-FILES-CPP-DEV-release-bundle-docs
Review OME Files documentation PRs OME-FILES-CPP-DEV-merge-docs

Configuration

For all jobs building documentation using Sphinx, the following environment variables are used:

  • the Sphinx building options, SPHINXOPTS, is set to -Dsphinx.opts="-W"
  • the release number of the documentation is set by OMERO_RELEASE, BF_RELEASE or by the relevant POM
  • the source code links use SOURCE_USER and SOURCE_BRANCH
  • for the Bio-Formats and OMERO sets of documentation, the name of the Jenkins job is set by JENKINS_JOB.

Note that the https://github.com/openmicroscopy/sphinx_theme repository is no longer used, this hosted the theme to match the old plone website.

OMERO 5.x series

The branch for the 5.x series of the OMERO documentation is develop.

OMERO-DEV-latest-docs

This job is used to review the PRs opened against the develop branch of the OMERO 5.x documentation

  1. Merges PRs using scc merge
  2. Runs make clean html to build the HTML Sphinx documentation
  3. Runs make linkcheck
OMERO-DEV-merge-docs

This job is used to review the PRs opened against the develop branch of the OMERO 5.x documentation

  1. Merges PRs using scc merge
  2. Pushes the branch to develop/merge/daily
  3. Runs make clean html to build the HTML Sphinx documentation
  4. Runs make linkcheck
OMERO-DEV-latest-docs-autogen

This job is used to build the latest auto-generated pages for the develop branch of the OMERO documentation

  1. Checks out the develop branch of ome-documentation.git
  2. Downloads the OMERO.server and OMERO.clients from OMERO-DEV-latest
  3. Runs the omero/autogen_docs autogeneration script
  4. Pushes the auto-generated changes to develop/latest/autogen
OMERO-DEV-merge-docs-autogen

This job is used to review the component auto-generation for the develop branch of the OMERO documentation

  1. Checks out develop/merge/daily
  2. Downloads the OMERO.server and OMERO.clients from OMERO-DEV-merge-build
  3. Runs the omero/autogen_docs autogeneration script
  4. Pushes the auto-generated changes to develop/merge/autogen

Bio-Formats 5.x series

The branch for the 5.x series of the Bio-Formats documentation is master.

BIOFORMATS-DEV-latest-docs

This job is used to build the master branch of the Bio-Formats documentation.

  1. Runs make clean html to build the HTML Sphinx documentation
  2. Runs make linkcheck
BIOFORMATS-DEV-merge-docs

This job is used to review the PRs opened against the master branch of the Bio-Formats documentation

  1. Merges PRs using scc merge
  2. Runs make clean html to build the HTML Sphinx documentation
  3. Runs make linkcheck

OME Model and OME Contributing

The OME Contributing documentation is located in the ome-documentation repository and is built from the develop branch. The Model documentation is located in the ome-model repository and is built from the master branch.

MODEL-merge-docs

This job is used to review the PRs opened against the master branch of the OME Model documentation

  1. Merges PRs using scc merge
  2. Runs make clean html to build the HTML Sphinx documentation
  3. Runs make linkcheck
CONTRIBUTING-merge-docs

This job is used to review the PRs opened against the develop branch of the OME Contributing documentation

  1. Merges PRs using scc merge
  2. Runs make clean html to build the HTML Sphinx documentation
  3. Runs make linkcheck
MODEL-latest-docs

This job is used to build the master branch of the OME Model documentation and publish the official documentation

  1. Runs make clean html to build the HTML Sphinx documentation
  2. Runs make linkcheck
CONTRIBUTING-latest-docs

This job is used to build the develop branch of the OME Contributing documentation and publish the official documentation

  1. Runs make clean html to build the HTML Sphinx documentation
  2. Runs make linkcheck

Jekyll websites

The following set of jobs is used to review or publish the content of the OME Jekyll websites.

WWW-merge

This job is used to review the PRs opened against the master branch of https://github.com/openmicroscopy/www.openmicroscopy.org

  1. Merges PRs using scc merge and pushes the branch to https://github.com/snoopycrimecop/www.openmicroscopy.org/tree/gh-pages
  2. The GitHub Pages service deploys the staging website content under https://snoopycrimecop.github.io/www.openmicroscopy.org/
OME-help-staging

This job is used to review the PRs opened against the master branch of https://github.com/openmicroscopy/ome-help

  1. Merges PRs using scc merge (and also incorporates cname_staging to allow deployment to a non-GitHub URL) then pushes the resulting branch to gh-pages
  2. The GitHub Pages service updates the content of https://help.staging.openmicroscopy.org
OME-help-release

This job is used to deploy the OME help documentation

  1. Opens a Pull Request from https://github.com/openmicroscopy/ome-help/tree/master to https://github.com/openmicroscopy/ome-help/tree/gh-pages. If this PR is merged, the GitHub Pages service updates the content of https://help.openmicroscopy.org

  2. If the build is promoted,
    1. rysnc the content of /ome/data_repo/public/help-staging to /ome/data_repo/public/help
FIGURE-help-staging

This job is used to review the PRs opened against the gh-pages-staging branch of https://github.com/ome/omero-figure.

  1. Merges PRs using scc merge (and also incorporates cname_staging to allow deployment to a non-GitHub URL) then pushes the resulting branch to gh-pages
  2. The GitHub Pages service updates the content of https://figure.staging.openmicroscopy.org
FIGURE-help-release

This job is used to deploy the Figure gh-pages website

  1. Opens a Pull Request from https://github.com/ome/omero-figure/tree/gh-pages-staging to https://github.com/ome/omero-figure/tree/gh-pages. If this PR is merged, the GitHub Pages service updates the content of https://figure.openmicroscopy.org

OME Files

This bundle of Sphinx documentation has three components: OME Model documentation is located in the ome-model repository; OME Files C++ documentation is located in the ome-files-cpp repository; OME CMake Super-Build documentation is located in the ome-cmake-superbuild repository. All are currently built from the master branches despite the build names.

OME-FILES-CPP-DEV-release-bundle-docs

This job is used to publish the master branches of the OME Model, OME Files C++ and OME CMake Super-Build Sphinx documentation as a single bundle

  1. Builds OME Files components and third-party dependencies using cmake
  2. Runs scc deploy to update https://docs.openmicroscopy.org/ome-files-cpp/

The merge and latest builds for this documentation set are detailed on the OME Files jobs page.