docs

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 CircleCI.

If you are logged in to CircleCI (it is possible to authenticate using your Github account), you can view the rendered changes.

To do this:

• click Details in the ci/circleci: docs check at the bottom of the Pull Request.
• click ARTIFACTS in the CircleCI dashboard
• browse to the documentation root at generated/docs/index.html.

How the Envoy website and docs are updated

1. The docs are published to docs/envoy/latest on every commit to master. This process is handled by CircleCI 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.