docs: Cleanups/improvements (envoyproxy#722)

Signed-off-by: Ryan Northey <ryan@synca.io>

Author: phlax

brotli/example.rst

@@ -8,13 +8,13 @@ Brotli
    .. include:: _include/docker-env-setup-link.rst
 
    :ref:`curl <start_sandboxes_setup_curl>`
-        Used to make ``HTTP`` requests.
+        Used to make HTTP requests.
 
 By enabling compression in Envoy you can save some network bandwidth, at the expense of increased processor usage.
 
 Envoy supports compression and decompression for both requests and responses.
 
-This sandbox provides an example of response compression served over ``HTTPS``.
+This sandbox provides an example of response compression served over HTTPS.
 
 The sandbox covers two scenarios:
 
@@ -24,12 +24,12 @@ The sandbox covers two scenarios:
 Step 1: Start all of our containers
 ***********************************
 
-Change to the ``examples/brotli`` directory and bring up the docker composition.
+Change to the ``brotli`` directory and bring up the docker composition.
 
 .. code-block:: console
 
     $ pwd
-    envoy/examples/brotli
+    examples/brotli
     $ docker compose pull
     $ docker compose up --build -d
     $ docker compose ps

cache/example.rst

@@ -11,16 +11,16 @@ Cache filter
    :ref:`curl <start_sandboxes_setup_curl>`
         Used to make ``HTTP`` requests.
 
-In this example, we demonstrate how HTTP caching can be utilized in Envoy by using the Cache Filter.
+In this example, we demonstrate how HTTP caching can be utilized in Envoy by using the Cache filter.
 The setup of this sandbox is based on the setup of the :ref:`Front Proxy sandbox <install_sandboxes_front_proxy>`.
 
 All incoming requests are routed via the front Envoy, which acts as a reverse proxy sitting on
-the edge of the ``envoymesh`` network.
+the edge of the Docker network.
 
-Port ``8000`` is exposed by :download:`docker-compose.yaml <_include/cache/docker-compose.yaml>` to handle ``HTTP`` calls
+Port ``8000`` is exposed by :download:`docker-compose.yaml <_include/cache/docker-compose.yaml>` to handle HTTP calls
 to the services. Two backend services are deployed behind the front Envoy, each with a sidecar Envoy.
 
-The front Envoy is configured to run the Cache Filter, which stores cacheable responses in an in-memory cache,
+The front Envoy is configured to run the Cache filter, which stores cacheable responses in an in-memory cache,
 and serves it to subsequent requests.
 
 In this demo, the responses that are served by the deployed services are stored in :download:`responses.yaml <_include/cache/responses.yaml>`.
@@ -37,12 +37,12 @@ Responses served from the backend service have no ``age`` header, and their ``da
 Step 1: Start all of our containers
 ***********************************
 
-Change to the ``examples/cache`` directory.
+Change to the ``cache`` directory.
 
 .. code-block:: console
 
     $ pwd
-    envoy/examples/cache
+    examples/cache
     $ docker compose pull
     $ docker compose up --build -d
     $ docker compose ps
@@ -56,13 +56,18 @@ Change to the ``examples/cache`` directory.
 Step 2: Test Envoy's HTTP caching capabilities
 **********************************************
 
-You can now send a request to both services via the ``front-envoy``. Note that since the two services have different routes,
-identical requests to different services have different cache entries (i.e. a request sent to service 2 will not be served by a cached
-response produced by service 1).
+You can now send a request to both services via the ``front-envoy``.
+
+.. note::
+   Since the two services have different routes,
+   identical requests to different services have different cache entries (i.e. a request sent to service 2 will not be served by a cached
+   response produced by service 1).
 
 To send a request:
 
-``curl -i localhost:8000/service/<service_no>/<response>``
+.. code-block:: console
+
+   $ curl -i localhost:8000/service/<service_no>/<response>
 
 ``service_no``: The service to send the request to, 1 or 2.
 

cors/example.rst

@@ -33,12 +33,12 @@ The CORS enforcement choices are:
 Step 1: Start all of our containers
 ***********************************
 
-Change to the ``examples/cors/frontend`` directory, and start the containers:
+Change to the ``cors/frontend`` directory, and start the containers:
 
 .. code-block:: console
 
   $ pwd
-  envoy/examples/cors/frontend
+  examples/cors/frontend
   $ docker compose pull
   $ docker compose up --build -d
   $ docker compose ps
@@ -53,7 +53,7 @@ Now, switch to the ``backend`` directory in the ``cors`` example, and start the
 .. code-block:: console
 
   $ pwd
-  envoy/examples/cors/backend
+  examples/cors/backend
   $ docker compose pull
   $ docker compose up --build -d
   $ docker compose ps
@@ -68,9 +68,9 @@ Step 2: Test Envoy's CORS capabilities
 
 You can now open a browser to view your frontend service at http://localhost:8000.
 
-Results of the cross-origin request will be shown on the page under *Request Results*.
+Results of the cross-origin request will be shown on the page under *Request results*.
 
-Your browser's ``CORS`` enforcement logs can be found in the browser console.
+Your browser's CORS enforcement logs can be found in the browser console.
 
 For example:
 
@@ -87,10 +87,10 @@ When Envoy runs, it can listen to ``admin`` requests if a port is configured.
 In the example configs, the backend admin is bound to port ``8003``.
 
 If you browse to http://localhost:8003/stats you will be able to view
-all of the Envoy stats for the backend. You should see the ``CORS`` stats for
+all of the Envoy stats for the backend. You should see the CORS stats for
 invalid and valid origins increment as you make requests from the frontend cluster.
 
-.. code-block:: none
+.. code-block:: yaml
 
   http.ingress_http.cors.origin_invalid: 2
   http.ingress_http.cors.origin_valid: 7

cors/frontend/index.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
 <head>
-    <title>Envoy CORS Webpage</title>
+    <title>Envoy CORS webpage</title>
     <link rel="shortcut icon" href="https://www.envoyproxy.io/img/favicon.ico">
     <script type="text/javascript">
         var client = new XMLHttpRequest();
@@ -56,7 +56,7 @@ <h5>CORS Enforcement</h5>
             <br/>
         </div>
         <div style="float:left;">
-            <h3>Request Results</h3>
+            <h3>Request results</h3>
             <p id="results"></p>
         </div>
     </div>

csrf/example.rst

@@ -19,27 +19,27 @@ deploys a service with both a frontend and backed. This service will be started
 on two different virtual machines with different origins.
 
 The frontend has a field to input the remote domain of where you would like to
-send POST requests along with radio buttons to select the remote domain's CSRF
+send ``POST`` requests along with radio buttons to select the remote domain's CSRF
 enforcement. The CSRF enforcement choices are:
 
   * Disabled: CSRF is disabled on the requested route. This will result in a
     successful request since there is no CSRF enforcement.
   * Shadow Mode: CSRF is not enforced on the requested route but will record
     if the request contains a valid source origin.
-  * Enabled: CSRF is enabled and will return a 403 (Forbidden) status code when
+  * Enabled: CSRF is enabled and will return a ``403 (Forbidden)`` status code when
     a request is made from a different origin.
-  * Ignored: CSRF is enabled but the request type is a GET. This should bypass
+  * Ignored: CSRF is enabled but the request type is a ``GET``. This should bypass
     the CSRF filter and return successfully.
 
 Step 1: Start all of our containers
 ***********************************
 
-Change to the ``examples/csrf/samesite`` directory, and start the containers:
+Change to the ``csrf/samesite`` directory, and start the containers:
 
 .. code-block:: console
 
   $ pwd
-  envoy/examples/csrf/samesite
+  examples/csrf/samesite
   $ docker compose pull
   $ docker compose up --build -d
   $ docker compose ps
@@ -54,7 +54,7 @@ Now, switch to the ``crosssite`` directory in the ``csrf`` example, and start th
 .. code-block:: console
 
   $ pwd
-  envoy/examples/csrf/crosssite
+  examples/csrf/crosssite
   $ docker compose up --build -d
   $ docker compose ps
 
@@ -75,8 +75,8 @@ with ``localhost``.
 To demonstrate same-site requests open the frontend service for ``samesite`` at http://localhost:8000
 and enter the IP address of the ``samesite`` machine as the destination.
 
-Results of the cross-site request will be shown on the page under *Request Results*.
-Your browser's ``CSRF`` enforcement logs can be found in the browser console and in the
+Results of the cross-site request will be shown on the page under *Request results*.
+Your browser's CSRF enforcement logs can be found in the browser console and in the
 network tab.
 
 For example:
@@ -86,7 +86,7 @@ For example:
   Failed to load resource: the server responded with a status of 403 (Forbidden)
 
 If you change the destination to be the same as one displaying the website and
-set the ``CSRF`` enforcement to enabled the request will go through successfully.
+set the CSRF enforcement to enabled the request will go through successfully.
 
 Step 3: Check stats of backend via admin
 ****************************************
@@ -98,7 +98,7 @@ If you browse to http://localhost:8001/stats you will be able to view
 all of the Envoy stats for the backend. You should see the CORS stats for
 invalid and valid origins increment as you make requests from the frontend cluster.
 
-.. code-block:: none
+.. code-block:: yaml
 
   http.ingress_http.csrf.missing_source_origin: 0
   http.ingress_http.csrf.request_invalid: 1

csrf/index.html

@@ -60,7 +60,7 @@ <h5>CSRF Enforcement</h5>
             <br/>
         </div>
         <div style="float:left;">
-            <h3>Request Results</h3>
+            <h3>Request results</h3>
             <p id="results"></p>
         </div>
     </div>

datadog-tracing/example.rst

@@ -7,11 +7,17 @@ Datadog tracing
 
    .. include:: _include/docker-env-setup-link.rst
 
-.. note:: Before proceeding, please ensure you have a Datadog account set up. If you don't already have one, you can `sign up for Datadog here <https://app.datadoghq.eu/signup>`_.
-
    :ref:`curl <start_sandboxes_setup_curl>`
         Used to make HTTP requests.
 
+
+.. note::
+
+   Before proceeding, please ensure you have a Datadog account set up.
+
+   If you don't already have one, you can `sign up for Datadog here <https://app.datadoghq.eu/signup>`_.
+
+
 The Datadog tracing sandbox demonstrates Envoy's :ref:`request tracing <arch_overview_tracing>`
 capabilities using `Datadog <https://datadoghq.com/>`_ as the tracing provider.
 
@@ -29,14 +35,12 @@ Each span records the latency of upstream API calls as well as information neede
 Step 1: Build the sandbox
 *************************
 
-Change directory to ``examples/datadog-tracing`` in the Envoy repository.
-
-To build this sandbox example, and start the example services run the following commands:
+Change to the ``datadog-tracing`` directory, and start the containers, with the following commands:
 
 .. code-block:: console
 
     $ pwd
-    envoy/examples/datadog-tracing
+    examples/datadog-tracing
     $ export DD_API_KEY=<YOUR_API_KEY>
     $ docker compose pull
     $ docker compose up --build -d

double-proxy/example.rst

@@ -1,7 +1,7 @@
 .. _install_sandboxes_double_proxy:
 
-Double proxy (with ``mTLS`` encryption)
-=======================================
+Double proxy (with mTLS encryption)
+===================================
 
 .. sidebar:: Requirements
 
@@ -13,7 +13,7 @@ Double proxy (with ``mTLS`` encryption)
    :ref:`openssl <start_sandboxes_setup_openssl>`
         Generate ``SSL`` keys and certificates.
 
-This sandbox demonstrates a basic "double proxy" configuration, in which a simple ``aiohttp`` app
+This sandbox demonstrates a basic "double proxy" configuration, in which a simple aiohttp app
 connects to a PostgreSQL database, with two Envoy proxies in between.
 
 ``Envoy (front)`` -> ``aiohttp`` -> ``Envoy (postgres-front)`` -> ``Envoy (postgres-back)`` -> ``PostgreSQL``
@@ -27,16 +27,16 @@ Another common use case is with Envoy configured to provide "Points of presence"
 and to relay requests to upstream servers and services.
 
 This example encrypts the transmission of data between the two middle proxies and provides mutual authentication
-using ``mTLS``.
+using mTLS.
 
 This can be useful if the proxies are physically separated or transmit data over untrusted networks.
 
-In order to  use the sandbox you will first need to generate the necessary ``SSL`` keys and certificates.
+In order to  use the sandbox you will first need to generate the necessary SSL keys and certificates.
 
 This example walks through creating a certificate authority, and using it to create a domain key and sign
 certificates for the proxies.
 
-Change to the ``examples/double-proxy`` directory.
+Change to the ``double-proxy`` directory.
 
 Step 1: Create a certificate authority
 **************************************
@@ -46,7 +46,7 @@ First create a key for the certificate authority:
 .. code-block:: console
 
    $ pwd
-   envoy/examples/double-proxy
+   examples/double-proxy
    $ mkdir -p certs
    $ openssl genrsa -out certs/ca.key 4096
    Generating RSA private key, 4096 bit long modulus (2 primes)
@@ -158,7 +158,7 @@ This will load the required keys and certificates into the frontend and backend
 .. code-block:: console
 
    $ pwd
-   envoy/examples/double-proxy
+   examples/double-proxy
    $ docker compose pull
    $ docker compose up --build -d
    $ docker compose ps
@@ -171,10 +171,10 @@ This will load the required keys and certificates into the frontend and backend
    double-proxy_proxy-postgres-backend_1    /docker-entrypoint.sh /usr ... Up           10000/tcp
    double-proxy_proxy-postgres-frontend_1   /docker-entrypoint.sh /usr ... Up           10000/tcp
 
-Step 6: Check the ``aiohttp`` app can connect to the database
-*************************************************************
+Step 6: Check the aiohttp app can connect to the database
+*********************************************************
 
-Checking the response at http://localhost:10000, you should see the output from the ``aiohttp`` app:
+Checking the response at http://localhost:10000, you should see the output from the aiohttp app:
 
 .. code-block:: console
 
@@ -187,4 +187,4 @@ Checking the response at http://localhost:10000, you should see the output from
       Outline of key concepts for securing Envoy.
 
    :ref:`TLS sandbox <install_sandboxes_tls>`
-      Examples of various ``TLS`` termination patterns with Envoy.
+      Examples of various TLS termination patterns with Envoy.