-
Notifications
You must be signed in to change notification settings - Fork 74
Building the docs
Three hosting sites are available for OpenJ9 user documentation:
- Staging site for testing and reviewing pull requests
- Draft documentation site for preparing documentation for the next OpenJ9 release:https://eclipse.github.io/openj9-docs/
- Published documentation site for the latest release of OpenJ9: https://www.eclipse.org/openj9/docs/
All build processes associated with these sites are driven from Eclipse Jenkins infrastructure.
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.
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.
📝 To run the pipeline script, you must be listed as an approved user in the Jenkins job.
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>.
📝 To run the pipeline script, you must be listed as an approved user in the Jenkins job.
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.
When the documentation for an OpenJ9 release is ready to publish, 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 master branch of the Eclipse OpenJ9 docs GIT repository. Changes to the master
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).