docs: Cleanups for 1.18.0 release

api/envoy/config/cluster/v3/cluster.proto

@@ -756,7 +756,7 @@ message Cluster {
   // in the :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   // upstream_http_protocol_options can be set via the cluster's
   // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
-  // See ref:`upstream_http_protocol_options
+  // See :ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
   core.v3.UpstreamHttpProtocolOptions upstream_http_protocol_options = 46
@@ -769,7 +769,7 @@ message Cluster {
   // in the :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   // common_http_protocol_options can be set via the cluster's
   // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
-  // See ref:`upstream_http_protocol_options
+  // See :ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
   core.v3.HttpProtocolOptions common_http_protocol_options = 29
@@ -780,7 +780,7 @@ message Cluster {
   // :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   // http_protocol_options can be set via the cluster's
   // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
-  // See ref:`upstream_http_protocol_options
+  // See :ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
   core.v3.Http1ProtocolOptions http_protocol_options = 13
@@ -796,7 +796,7 @@ message Cluster {
   // :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>`
   // message. http2_protocol_options can be set via the cluster's
   // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
-  // See ref:`upstream_http_protocol_options
+  // See :ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
   core.v3.Http2ProtocolOptions http2_protocol_options = 14 [

api/envoy/config/route/v3/route_components.proto

@@ -455,7 +455,7 @@ message RouteMatch {
     // where Extended CONNECT requests may have a path, the path matchers will work if
     // there is a path present.
     // Note that CONNECT support is currently considered alpha in Envoy.
-    // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
+    // [#comment: TODO(htuch): Replace the above comment with an alpha tag.]
     ConnectMatcher connect_matcher = 12;
   }
 
@@ -770,7 +770,7 @@ message RouteAction {
     // Configuration for sending data upstream as a raw data payload. This is used for
     // CONNECT requests, when forwarding CONNECT payload as raw TCP.
     // Note that CONNECT support is currently considered alpha in Envoy.
-    // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
+    // [#comment: TODO(htuch): Replace the above comment with an alpha tag.]
     ConnectConfig connect_config = 3;
   }
 

api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto

@@ -239,7 +239,7 @@ message HttpConnectionManager {
     google.protobuf.BoolValue enabled = 3;
   }
 
-  // [#not-implemented-hide] Transformations that apply to path headers. Transformations are applied
+  // [#not-implemented-hide:] Transformations that apply to path headers. Transformations are applied
   // before any processing of requests by HTTP filters, routing, and matching. Only the normalized
   // path will be visible internally if a transformation is enabled. Any path rewrites that the
   // router performs (e.g. :ref:`regex_rewrite
@@ -249,7 +249,7 @@ message HttpConnectionManager {
   //
   // Note: access logging and tracing will show the original *:path* header.
   message PathNormalizationOptions {
-    // [#not-implemented-hide] Normalization applies internally before any processing of requests by
+    // [#not-implemented-hide:] Normalization applies internally before any processing of requests by
     // HTTP filters, routing, and matching *and* will affect the forwarded *:path* header. Defaults
     // to :ref:`NormalizePathRFC3986
     // <envoy_api_msg_type.http.v3.PathTransformation.Operation.NormalizePathRFC3986>`. When not
@@ -259,7 +259,7 @@ message HttpConnectionManager {
     // normalization due to disallowed characters.)
     type.http.v3.PathTransformation forwarding_transformation = 1;
 
-    // [#not-implemented-hide] Normalization only applies internally before any processing of
+    // [#not-implemented-hide:] Normalization only applies internally before any processing of
     // requests by HTTP filters, routing, and matching. These will be applied after full
     // transformation is applied. The *:path* header before this transformation will be restored in
     // the router filter and sent upstream unless it was mutated by a filter. Defaults to no

api/envoy/extensions/wasm/v3/wasm.proto

@@ -46,7 +46,7 @@ message VmConfig {
   // VM plugin) to determine which VM will be used for the plugin. All plugins which use the same
   // *vm_id* and code will use the same VM. May be left blank. Sharing a VM between plugins can
   // reduce memory utilization and make sharing of data easier which may have security implications.
-  // See ref: "TODO: add ref" for details.
+  // [#comment: TODO: add ref for details.]
   string vm_id = 1;
 
   // The Wasm runtime type.

docs/build.sh

@@ -171,6 +171,8 @@ rsync -av \
       "${SCRIPT_DIR}"/_ext \
       "${GENERATED_RST_DIR}"
 
+bazel run "${BAZEL_BUILD_OPTIONS[@]}" //tools/code_format:rst_check "${GENERATED_RST_DIR}"
+
 # To speed up validate_fragment invocations in validating_code_block
 bazel build "${BAZEL_BUILD_OPTIONS[@]}" //tools/config_validation:validate_fragment
 

docs/root/faq/debugging/why_is_envoy_sending_413s.rst

@@ -3,4 +3,4 @@
 Why is Envoy sending 413s?
 ==========================
 
-Envoy by default imposes limits to how much it will buffer for a given request. Generally, Envoy filters are designed to be streaming, and will pass data from downstream to upstream, or will simply pause processing while waiting for an external event (e.g. doing auth checks). Some filters, for example the buffer filter, require buffering the full request or response. If a request body is too large to buffer, but buffering is required by the filter, Envoy will send a 413. The buffer limits can be increased at the risk of making OOMs more possible. Please see the ref:`flow control docs <faq_flow_control>` for details.
+Envoy by default imposes limits to how much it will buffer for a given request. Generally, Envoy filters are designed to be streaming, and will pass data from downstream to upstream, or will simply pause processing while waiting for an external event (e.g. doing auth checks). Some filters, for example the buffer filter, require buffering the full request or response. If a request body is too large to buffer, but buffering is required by the filter, Envoy will send a 413. The buffer limits can be increased at the risk of making OOMs more possible. Please see the :ref:`flow control docs <faq_flow_control>` for details.

docs/root/start/quick-start/_include/envoy-demo.yaml

@@ -50,9 +50,3 @@ static_resources:
       typed_config:
         "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
         sni: www.envoyproxy.io
-
-admin:
-  address:
-    socket_address:
-      address: 0.0.0.0
-      port_value: 9901

docs/root/start/quick-start/configuration-static.rst

@@ -42,7 +42,7 @@ All paths are matched and routed to the ``service_envoyproxy_io``
     :language: yaml
     :linenos:
     :lines: 1-34
-    :emphasize-lines: 3-32
+    :emphasize-lines: 3-31
 
 .. _start_quick_start_static_clusters:
 
@@ -54,6 +54,6 @@ proxies over ``TLS`` to https://www.envoyproxy.io.
 
 .. literalinclude:: _include/envoy-demo.yaml
     :language: yaml
-    :lineno-start: 32
-    :lines: 32-53
-    :emphasize-lines: 3-22
+    :lineno-start: 29
+    :lines: 29-52
+    :emphasize-lines: 5-24

docs/root/start/quick-start/run-envoy.rst

@@ -157,13 +157,6 @@ Check Envoy is proxying on http://localhost:10000.
    $ curl -v localhost:10000
    ...
 
-The Envoy admin endpoint should also be available at http://localhost:9901.
-
-.. code-block:: console
-
-   $ curl -v localhost:9901
-   ...
-
 You can exit the server with `Ctrl-c`.
 
 See the :ref:`admin quick start guide <start_quick_start_admin>` for more information about the Envoy admin interface.
@@ -325,7 +318,7 @@ to ``/dev/stdout``:
    :linenos:
    :lineno-start: 12
    :lines: 12-22
-   :emphasize-lines: 4-8
+   :emphasize-lines: 4-7
 
 The default configuration in the Envoy Docker container also logs access in this way.