Skip to content

Building the docs

Jump to bottom
Peter Shipton edited this page Feb 15, 2023 · 8 revisions

Three hosting sites are available for OpenJ9 user documentation:

All build processes associated with these sites are driven from Eclipse Jenkins infrastructure.

Eclipse Jenkins instance

Jobs run on the Eclipse OpenJ9 Jenkins instance.

The user documentation jobs use Docker containers that run from an image that is pulled from Docker hub.

Building the Docker image

The image is built from the buildenv/DockerFile, which contains all the components required to build and test the user documentation.

Changes to the image are tested and updated by using a pull request. Typing Jenkins build container in a PR that contains Dockerfile changes runs a pipeline script that pushes a new Docker image to Docker Hub with a tag name that matches the PR number. You can pull this image and run a local build of the documentation source to verify changes. When verified, merge the PR and run Build-Doc-Docker_Container to update the image at Docker hub.

⚠️ When updating the container to use later versions of MkDocs and MkDocs-material, changes might be required to CSS and javascript files.

📝 To run the pipeline script, you must be listed as an approved user in the Jenkins job.

Staging site

The staging environment is provided on GitHub pages, which is built from the openJ9-docs-staging repository.

To stage updated docs, trigger a job from a pull request by typing Jenkins doc stage in a comment field. This comment triggers a pipeline script that builds and publishes the content to https://eclipse.github.io/openj9-docs-staging/<pull_request_number>. The pipeline script copies the theme/base.html file from the Material source in the Docker container and injects some HTML markup so that a banner is displayed on every page to distinguish it from the production documentation.

📝 To run the pipeline script, you must be listed as an approved user in the Jenkins job.

Draft documentation

When a pull request is reviewed and approved, the PR is merged by a committer. The merge job triggers a pipeline script that builds and publishes the documentation to the Draft OpenJ9 user documentation. The pipeline script copies the theme/base.html file from the Material source in the Docker container and injects some HTML markup so that a banner is displayed on every page to distinguish it from the production documentation.

Published documentation

When the documentation for an OpenJ9 release is ready to publish (ie it's complete and there are no errors from the "mkdocs build" command in the log output from the draft build), a release branch is created on the openj9-docs repository with the naming format openj9-docs-0.XX.0.

At the appropriate time, this branch is published to the Eclipse website by running the Build-Doc-Push_to_Eclipse job, which takes a parameter of RELEASE_BRANCH (i.e. openj9-docs-0.XX.0).

This job builds and deploys the release branch to the main branch of the Eclipse OpenJ9 docs GIT repository. Changes to the main branch trigger a publication to the Eclipse OpenJ9 user documentation site.

The job also runs a special build of the documentation for offline use and puts a zip (openj9-docs-0.XX.0.zip) of this content in the Downloads directory of the openj9-docs repository (master). The special build adds a string to the MkDocs configuration file (mkdocs.yml) to set use_directory_urls: false, which is configured by the pipeline script during a merge request.

Clone this wiki locally