Documentation Editing and Contribution

Writing Documentation

We welcome contributions to documentation!

Running the site

If you clone the repository and run make site-server from the build directory, this will run the live hugo server, running as a showing the next version’s content and upcoming publishedDate’d content as well. This is likely to be the next releases’ version of the website.

To show the current website’s view, run it as make site-server ENV=RELEASE_VERSION=1.58.0 ARGS=

Platform

This site and documentation is built with a combination of Hugo, static site generator, with the Docsy theme for open source documentation.

• Hugo Documentation
• Docsy Guide
• Link Checker

Documentation for upcoming features

Unlike code, which has releases every 6 weeks, the documentation is published immediately when merged into main. This means that documentation for features not yet released needs to be gated, so it only becomes visible once the corresponding release is made.

There are two approaches for hiding documentation for upcoming features, such that it only gets published when the version is incremented on the release:

At the Page Level

Use publishDate and expiryDate in Hugo Front Matter to control when the page is displayed (or hidden). You can look at the Release Calendar to align it with the next release candidate release date - or whichever release is most relevant.

Within a Page

We have a feature shortcode that can be used to show, or hide sections of pages based on the current semantic version (set in config.toml, and overwritable by env variable).

For example, to show a section only from 1.24.0 forwards:

{{% feature publishVersion="1.24.0" %}}
  This is my special content that should only display >= 1.24.0
{{% /feature %}}

or to hide a section from 1.24.0 onward:

{{% feature expiryVersion="1.24.0" %}}
  This is my special content that will be hidden >= 1.24.0
{{% /feature %}}

Regenerate Diagrams

To regenerate the PlantUML or Dot diagrams, delete the .png version of the file in question from /site/static/diagrams/, and run make site-images.