This repository is wired via CI/CD and scripts to listen to component dependencies and upon their release to build a new version of the documentation for them and publish it.
The repositories involved in the process are:
- /gardener/website-generator (this repository). It contains the CI/CD pipeline definition and related scripts, configuration for building the website with HUGO, including all common framework html, styles, javascript and images, as well as the scripts and build configuration for the build environment container image.
- /gardener/component is any repository in the Gardener organization contributing Docforge documentation manifest, for which /gardener/website-generator is configured to listen for releases. The repository /gardener/documentation is one such example. It contains source content for the website, used by the builder to produce the static HTML to be served.
Currently, /gardener/documentation is configured to deliver the Gardener (cross-component) documentation along with the other website content assets (blogs/adopters/community), but it is transitioning to a repository dedicated to only crosscutting documentation, such as tutorials and website content. The Gardener repository will be configured to contribute its own documentation upon release. All other components wil follow using the same scheme depicted on the diagram.
- /gardener/website is the home repository for the https://gradener.cloud website. It hosts the website content produced by the website-generator and is configured to have it served by GitHub Pages.
The website builds and deployments are orchestrated by Concourse CI/CD pipeline and triggered upon depending component release or upon changes in /gardener/documentation or /gardener/website-generator repositories. The build results are then pushed to /gardener/website/docs and served as a GitHub Pages site.
Creating a local version of Docforge will allow you to preview changes you have made to the site locally, without the need to use GitHub UI.
Before you can setup your local version of the website, you need to have:
-
Clone the repository and go to the repo's directory.
-
Enter
git submodule update --init --recursive
. -
Export the following environment variables:
export GIT_OAUTH_TOKEN=<token>
-
cd
in hugo directory and runnpm install
-
Run
make build
command -
Run
cd hugo && hugo serve
In order to test local changes, for example gardener/documentation changes, you need to go trough the following steps:
-
Clone the repository where you will do the changes. We will take for example gardener/documentation.
-
Make the wanted changes there.
-
Create
${HOME}/.docforge/config
file with the following content in it:resourceMappings: https://github.com/gardener/documentation: <Path to the cloned documentation repo>
-
Run
make build
-
Run
cd hugo && hugo serve