Documentation testing

First, start a local document server that automatically refreshes when you save files for real-time preview. It relies on the cilium/docs-builder Docker container.

Set up your development environment

To run Cilium’s documentation locally, you need to install docker engine and also the make package. To verify that make and docker is installed, run the command make --version and docker --version in your terminal.

$ docker --version
Docker version 20.10.22, build 3a2c30b
$ make --version
GNU Make 4.2.1

For Windows

Note

The preferred method is to upgrade to Windows 10 version 1903 Build 18362 or higher, you can upgrade to Windows Subsystem for Linux WSL2 and run make in Linux.

  1. Verify you have access to the make command in your WSL2 terminal.

  2. Download and install docker desktop.

  3. Set up docker to use WSL2 as backend.

  4. Start docker desktop.

Preview documentation locally

Navigate to the root of the folder where you cloned the project, then run the code below in your terminal:

$ make render-docs

This will build a docker image and start a docker container. Preview the documentation at http://localhost:9081/ as you make changes. After making changes to Cilium documentation you should check that you did not introduce any new warnings or errors, and also check that your changes look as you intended one last time before opening a pull request. To do this you can build the docs:

$ make test-docs

Note

By default, render-docs generates a preview with instructions to install Cilium from the latest version on GitHub (i.e. from the HEAD of the main branch that has not been released) regardless of which Cilium branch you are in. You can target a specific branch by specifying READTHEDOCS_VERSION environment variable:

READTHEDOCS_VERSION=v1.7 make render-docs

Submit local changes on GitHub (Pull Request)

See the submit a pull request section of the contributing guide.