Building documentation locally

There are two methods to build the documentation, described below.

In both cases, the generated output can be found in generated/docs.

Building in an existing Envoy development environment

If you have an existing Envoy development environment, you should have the necessary dependencies and requirements and be able to build the documentation directly.

./docs/build.sh

By default configuration examples are going to be validated during build. To disable validation, set SPHINX_SKIP_CONFIG_VALIDATION environment variable to true:

SPHINX_SKIP_CONFIG_VALIDATION=true docs/build.sh

Using the Docker build container to build the documentation

If you do not have an existing development environment, you may wish to use the Docker build image that is used in continuous integration.

This can be done as follows:

./ci/run_envoy_docker.sh 'docs/build.sh'

To use this method you will need a minimum of 4-5GB of disk space available to accommodate the build image.

Creating a Pull Request with documentation changes

When you create a Pull Request the documentation is rendered by Azure Pipelines.

To do this:

1. Open docs job in Azure Pipelines.
2. Navigate to "Upload Docs to GCS" log.
3. Click on the link there.

How the Envoy website and docs are updated

1. The docs are published to docs/envoy/latest on every commit to main. This process is handled by Azure Pipelines with the publish.sh script.

2. The docs are published to docs/envoy in a directory named after every tagged commit in this repo. Thus, on every tagged release there are snapped docs.