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