There are two methods to build the documentation, described below.
In both cases, the generated output can be found in generated/docs
.
If you have an existing Envoy development environment, you should have the necessary dependencies and requirements and be able to build the documentation directly.
If using the Docker build container, you can run:
./ci/do_ci.sh docs
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 ./ci/do_ci.sh docs
If not using the Docker build container, you can run:
bazel run --//tools/tarball:target=//docs:html //tools/tarball:unpack "$PWD"/generated/docs/
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 './ci/do_ci.sh docs'
To use this method you will need a minimum of 4-5GB of disk space available to accommodate the build image.
When you create a Pull Request the documentation is rendered by Azure Pipelines.
To do this:
- Open docs job in Azure Pipelines.
- Navigate to "Upload Docs to GCS" log.
- Click on the link there.
The docs are published dynamically by Netlify on every commit to main. This process is handled by the envoy-website repo
For tagged commits the docs are built statically by the archive repo, which in turn triggers a rebuild of the website.