Can no longer build docs on macOS

[kenjenkins]

Title: Can no longer build docs on macOS

Description:

Previously the instructions at https://github.com/envoyproxy/envoy/blob/main/docs/README.md could be used to build the documentation on macOS, using the docs/build.sh script.

After #29887 this script has been removed, and the ci/do_ci.sh docs command does not appear to work on macOS:

$ SPHINX_SKIP_CONFIG_VALIDATION=true docs/build.sh
This script has been removed. Please use `ci/do_ci.sh docs` instead
$ SPHINX_SKIP_CONFIG_VALIDATION=true ci/do_ci.sh docs
grep: /proc/cpuinfo: No such file or directory

Relevant Links:

• https://stackoverflow.com/questions/68780116/is-there-any-alternative-for-proc-in-macos

[phlax]

@kenjenkins the supported way to run these is in the docker build container (ie using ./ci/run_envoy_docker.sh although tbf im not a mac user (and dont use that container so much) so not sure that would make /proc/cpuinfo available

happy to review a pr to resolve this, but i dont have anything to test on

[phlax]

we also need to update docs re the ./docs/build.sh path

[kenjenkins]

It seems odd to me that building Envoy itself should work fine on macOS, but not building the Envoy documentation.

Is there a downside to providing instructions something like these, for building outside of docker?

bazel build //docs:html
rm -rf generated/docs/ && mkdir -p generated/docs/
tar -xzf bazel-bin/docs/html.tar.gz -C generated/docs/

[phlax]

no - the docs need an update with something like that - altho i would suggest more this pattern

$ bazel run --//tools/tarball:target=//docs:html //tools/tarball:unpack $ABS_PATH_TO_OUTPUT_DIR

using ci/do_ci.sh can be a mixed blessing - i would like to make it work flexibly tbh - no idea about mac support with that codepath

[phlax]

Is there a downside to providing instructions something like these

thinking further - sort of yes

using the build container is the recommended way - and in that case its probably a good idea to use ci/do_ci.sh

the main upside to using containers is the isolation the provide

there is also some benefit wrt to expected host versions - but we are working towards using hermetic/bazel tooling throughout ci which kinda eliminates this benefit

[kenjenkins]

Thanks for merging #30193, I think we can close this now.