Make it easier to build docs

[phlax]

description

The current documentation for building the docs (https://github.com/envoyproxy/envoy/blob/master/docs/README.md) tell you to run:

./docs/build.sh

I guess this works if you have a local dev environment - but quite a few thing are needed - so it doesnt work out of the box at least on a minimal linux install.

It seems you can build docs reliably like this with docker:

./ci/run_envoy_docker.sh 'ci/do_ci.sh docs'

The main problem for me with this was that it downloads a very large docker image. Again this is probably not a big problem if you are developing or building locally - but if you want to make "drive-by" docs changes and see the results ~immediately its not ideal.

I opened a PR on envoy-build-tools here (envoyproxy/envoy-build-tools#92) to try and build a slimmed down container - but my first attempt wasnt optimal (see PR for discussion)

At very least, i think we need to update the docs with some of the above info.

refs

• https://github.com/envoyproxy/envoy/blob/master/docs/README.md
• [WIP] Add minimal container for building docs envoy-build-tools#92

[mattklein123]

Agreed I've heard multiple complaints around this. Anything we can do to make this faster and easier would be appreciated.

cc @htuch also who may have ideas of how we can improve the docs build speed, especially once we get rid of v2.

[phlax]

a related thought i have been having is that we could make it so that ci pushes the build docs to eg a gh-pages repo/branch for each PR/commit head - so contributors/reviewers can see rendered changes

it would probably need some kind of branch garbage collection i think

im happy to follow up on this ticket

[mattklein123]

a related thought i have been having is that we could make it so that ci pushes the build docs to eg a gh-pages repo for each PR - so contributors/reviewers can see rendered changes

This is already done. See the artifacts tab inside the circle ci docs job.

[phlax]

This is already done.

k - ill take a look - and add any relevant docs that might make it more obvious on where to look for rendered docs

[mattklein123]

Awesome thank you.

[phlax]

@dio (or others) would you mind assigning this ticket to me

[htuch]

I think docs build has some overhead from the proto builds for the API docs via protodoc etc. (which are still there when we get rid of v2, but maybe 2x speed), and then there are two interesting bottlenecks to optimize:

1. The Sphinx build is Python and held hostage by GIL. There is a Sphinx -j option where it can try use threads or multiprocessing, but it requires all plugins to support this. Last time I tried turning it on, it didn't work due to some plugin that didn't. It might be good to revisit this.
2. When we start to incorporate WIP: Validating config in docs #11394, e.g. if we were to switch the probably hundreds of examples over today, we will see fairly significant increases in build time, as each invocation takes a few seconds. @dmitri-d did you have any thoughts on optimizing this as we scale up? I remember we chatted about a few options.

[dmitri-d]

When we start to incorporate #11394, e.g. if we were to switch the probably hundreds of examples over today, we will see fairly significant increases in build time, as each invocation takes a few seconds. @dmitri-d did you have any thoughts on optimizing this as we scale up?

Not optimizing as much as changing the approach: instead of doing validation during the doc build, we could extract validation into a dedicated step, to be performed using a custom builder (see https://www.sphinx-doc.org/en/master/usage/builders/index.html for some context). This should significantly reduce invocation time as we won't be launching external processes to perform validation.

An issue with this approach is that it would require executing sphinx from under bazel (which is doable, but requires work).

[moderation]

I'd request that we add instructions for Docker vs. replace instruction on how to build docs with a local environment and without Docker. I'm on Linux and won't install Docker

[phlax]

I'd request that we add instructions for Docker vs. replace

@moderation iiuc that is what i did - see #13268