Skip to content

Latest commit

 

History

History
109 lines (64 loc) · 3.91 KB

README.adoc

File metadata and controls

109 lines (64 loc) · 3.91 KB
Raw
Table of Contents

Publishing Eclipse Che documentation

Understanding the publication workflow

The publication workflow is the following:

Source Repository ⇒ Publication repository ⇒ Publication website

Publication website (https://www.eclipse.org/che/)

Eclipse Che website containing:

Eclipse Che website

https://www.eclipse.org/che/ Landing page and PHP website.

Eclipse Che documentation

https://www.eclipse.org/che/docs/ Documentation in HTML format.

Publication repository (https://git.eclipse.org/c/www.eclipse.org/che.git/)

Git repository containing:

docs directory

Eclipse Che documentation content in HTML format.

_ directory

Eclipse Che documentation UI requirements.

other directories

Eclipse Che website.

A process managed by the Eclipse Infrastructure team pushes the content of the Publication repository to the Publication website.

Source repository (https://github.com/eclipse/che-docs/)

Git repository containing the sources for the Eclipse Che documentation in the form of a Modular Documentation compliant Antora component.

publication branch

Git branch containing the docs content to publish to the publication repository.

publication-builder branch

Git branch building, validation and publishing the documentation website to the publication branch.

Antora playbook (publication-builder-antora-playbook.yml)

Antora playbook defining how to assemble the documentation, and which release branches to publish.

Antora UI ([supplemental-ui])

Additions to the default Antora UI, defining the menu and style refinements.

GitHub workflow (.github/workflows/publication-builder.yml)

GitHub workflow orchestrating the publication.

Release branches

The release branches contain the documentation content in the form of a Modular Documentation compliant Antora component.

antora.yml

Antora component version descriptor present in each release branch.

.github/workflows/call-publication-builder.yaml

GitHub workflow calling the Publication builder workflow. See: Call publication builder runs.

Checking Eclipse Che documentation publication continuous integration status

Procedure

  1. Check the most recent Call publication builder GitHub workflow run completed successfully.

  2. Check the most recent Eclipse Jenkins pipeline run completed successfully.

Next steps

When at least one job run failed:

  1. Escalate to #forum-devtools-docs.

  2. If necessary, report an issue on Eclipse Foundation bug tracker.

Building for publication on Eclipse Che hosted by Red Hat

Procedure

  1. Open a workspace containing the Source repository publication-builder branch

  2. Run the Publication builder task to assemble the documentation in HTML format.

  3. Validate the build artifacts in the build/site directory.

Building for publication on a local environment

Procedure

  1. Checkout the Source repository publication-builder branch to get the publication instructions.

  2. Run the tools/runnerpublication-builder.sh script to assemble the documentation in HTML format:

    $ ./tools/runnerpublication-builder.sh

  3. Validate the build artifacts in the build/site directory.