docs: Update build instructions for docs

docs/README.md

@@ -1,16 +1,48 @@
-# Developer-local docs build
+# 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](https://github.com/envoyproxy/envoy/tree/master/bazel#quick-start-bazel-build-for-developers), you should have the necessary dependencies and requirements and be able to build the documentation directly.
 
 ```bash
 ./docs/build.sh
 ```
 
-The output can be found in `generated/docs`. By default configuration examples are going to be validated during build. 
-To disable validation, set `SPHINX_SKIP_CONFIG_VALIDATION` environment variable to `true`:
+By default configuration examples are going to be validated during build. To disable validation,
+set `SPHINX_SKIP_CONFIG_VALIDATION` environment variable to `true`:
 
 ```bash
 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 '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.
+
+# 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