Documentation Engineering: Publish Versioned Gardener Documentation

[g-pavlov]

Documentation Engineering

Milestone stage in #51

Publish Versioned Gardener Documentation

Provide the toolset and establish the process and the delivery pipeline for having the Gardener Documentation published with versions on https://gardener.cloud in a manner consumable for other documentation shipments too.

Process

Releases from the gardener/gardener repository trigger automatic pull requests for update of the latest Gardener release version maintained in gardener/documentation repository. Once all supplementary material, such as tutorials and cross-cutting concerns, is ready for documentation release, the release is triggered in Concourse. The gardener/documentation and gardener/gardener release versions match.

Releasing the gardener/documentation triggers a release PR to the gardener/website-generator repo. This automatically starts the process for building a set of documentation bundles, one for each version supported on the website, and the rest of the website assets into a publishable bundle.

Finally, the bundle is pushed to the gardener/website where it is taken over and published by GitHub pages as website content.

The described process applies to the documentation only. Changes to blogs or other sections of the website, beyond documentation are still reflected immediately with an automated build and publish and do not require gardener/documentation release.

Versions scope

The published Gardener documentation versions are up to the 3 latest minor versions, the latest patch number of each.

Tools

To support the process we employ the docforge tool. It is intended to takeover completely from the current variety of tools and scripts employed for site building. Using it, the whole intended website structure can be pulled and forge into source suitable for building and publishing with Hugo, all that regardless of the physical locations of the original sources. The intended website structure is described with yaml manifests. The gardener/documentation repository maintains one and its versioned state is used at build time to build a documentation bundle in a version with the website accordingly.

[Kristian-ZH]

We already addressed this