docs/api: Fix RST backtick errors and enforce (envoyproxy#29898)

Signed-off-by: Ryan Northey <[email protected]>

api/contrib/envoy/extensions/filters/network/generic_proxy/v3/route.proto

@@ -43,7 +43,7 @@ message VirtualHost {
   xds.type.matcher.v3.Matcher routes = 3 [(validate.rules).message = {required: true}];
 }
 
-// The generic proxy makes use of the `xds matching API` for routing configurations.
+// The generic proxy makes use of the xDS matching API for routing configurations.
 //
 // In the below example, we combine a top level tree matcher with a linear matcher to match
 // the incoming requests, and send the matching requests to v1 of the upstream service.

api/envoy/config/core/v3/address.proto

@@ -151,7 +151,7 @@ message BindConfig {
   // precompiled binaries.
   repeated SocketOption socket_options = 3;
 
-  // Extra source addresses appended to the address specified in the `source_address`
+  // Extra source addresses appended to the address specified in the ``source_address``
   // field. This enables to specify multiple source addresses.
   // The source address selection is determined by :ref:`local_address_selector
   // <envoy_v3_api_field_config.core.v3.BindConfig.local_address_selector>`.

api/envoy/config/core/v3/protocol.proto

@@ -96,11 +96,11 @@ message QuicProtocolOptions {
   QuicKeepAliveSettings connection_keepalive = 5;
 
   // A comma-separated list of strings representing QUIC connection options defined in
-  // `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>` and to be sent by upstream connections.
+  // `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>`_ and to be sent by upstream connections.
   string connection_options = 6;
 
   // A comma-separated list of strings representing QUIC client connection options defined in
-  // `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>` and to be sent by upstream connections.
+  // `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>`_ and to be sent by upstream connections.
   string client_connection_options = 7;
 }
 

api/envoy/config/endpoint/v3/endpoint_components.proto

@@ -88,8 +88,8 @@ message Endpoint {
   // :ref:`auto_host_rewrite <envoy_v3_api_field_config.route.v3.RouteAction.auto_host_rewrite>`.
   string hostname = 3;
 
-  // An ordered list of addresses that together with `address` comprise the
-  // list of addresses for an endpoint. The address given in the `address` is
+  // An ordered list of addresses that together with ``address`` comprise the
+  // list of addresses for an endpoint. The address given in the ``address`` is
   // prepended to this list. It is assumed that the list must already be
   // sorted by preference order of the addresses. This will only be supported
   // for STATIC and EDS clusters.

api/envoy/config/listener/v3/listener.proto

@@ -249,7 +249,7 @@ message Listener {
   // Additional socket options that may not be present in Envoy source code or
   // precompiled binaries. The socket options can be updated for a listener when
   // :ref:`enable_reuse_port <envoy_v3_api_field_config.listener.v3.Listener.enable_reuse_port>`
-  // is `true`. Otherwise, if socket options change during a listener update the update will be rejected
+  // is ``true``. Otherwise, if socket options change during a listener update the update will be rejected
   // to make it clear that the options were not updated.
   repeated core.v3.SocketOption socket_options = 13;
 

api/envoy/config/metrics/v3/stats.proto

@@ -121,8 +121,8 @@ message StatsMatcher {
   // limited by either an exclusion or an inclusion list of :ref:`StringMatcher
   // <envoy_v3_api_msg_type.matcher.v3.StringMatcher>` protos:
   //
-  // * If ``reject_all`` is set to `true`, no stats will be instantiated. If ``reject_all`` is set to
-  //   `false`, all stats will be instantiated.
+  // * If ``reject_all`` is set to ``true``, no stats will be instantiated. If ``reject_all`` is set to
+  //   ``false``, all stats will be instantiated.
   //
   // * If an exclusion list is supplied, any stat name matching *any* of the StringMatchers in the
   //   list will not instantiate.

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

@@ -1193,7 +1193,7 @@ message RouteAction {
   // :ref:`host_rewrite_path_regex <envoy_v3_api_field_config.route.v3.RouteAction.host_rewrite_path_regex>`)
   // causes the original value of the host header, if any, to be appended to the
   // :ref:`config_http_conn_man_headers_x-forwarded-host` HTTP header if it is different to the last value appended.
-  // This can be disabled by setting the runtime guard `envoy_reloadable_features_append_xfh_idempotent` to false.
+  // This can be disabled by setting the runtime guard ``envoy_reloadable_features_append_xfh_idempotent`` to false.
   bool append_x_forwarded_host = 38;
 
   // Specifies the upstream timeout for the route. If not specified, the default is 15s. This

api/envoy/config/trace/v3/zipkin.proto

@@ -75,7 +75,7 @@ message ZipkinConfig {
   //
   // * The Envoy Proxy is used as gateway or ingress.
   // * The Envoy Proxy is used as sidecar but inbound traffic capturing or outbound traffic capturing is disabled.
-  // * Any case that the `start_child_span of router <envoy_v3_api_field_extensions.filters.http.router.v3.Router.start_child_span>` is set to true.
+  // * Any case that the :ref:`start_child_span of router <envoy_v3_api_field_extensions.filters.http.router.v3.Router.start_child_span>` is set to true.
   //
   // .. attention::
   //

api/envoy/config/upstream/local_address_selector/v3/default_local_address_selector.proto

@@ -23,9 +23,9 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // is appended to the address specified in the
 // :ref:`source_address <envoy_v3_api_field_config.core.v3.BindConfig.source_address>`
 // field. The extra address should have a different IP version than the address in the
-// `source_address` field. The address which has the same IP
+// ``source_address`` field. The address which has the same IP
 // version with the target host's address IP version will be used as bind address.
-// If there is no same IP version address found, the address in the `source_address` field will
+// If there is no same IP version address found, the address in the ``source_address`` field will
 // be returned.
 message DefaultLocalAddressSelector {
 }

api/envoy/extensions/clusters/dynamic_forward_proxy/v3/cluster.proto

@@ -60,7 +60,7 @@ message ClusterConfig {
   // resolved address for the new connection matches the peer address of the connection and
   // the TLS certificate is also valid for the new hostname. For example, if a connection
   // has previously been established to foo.example.com at IP 1.2.3.4 with a certificate
-  // that is valid for `*.example.com`, then this connection could be used for requests to
+  // that is valid for ``*.example.com``, then this connection could be used for requests to
   // bar.example.com if that also resolved to 1.2.3.4.
   //
   // .. note::

api/envoy/extensions/filters/http/compressor/v3/compressor.proto

@@ -126,18 +126,18 @@ message Compressor {
   //    ``<stat_prefix>.compressor.<compressor_library.name>.<compressor_library_stat_prefix>.*``.
   ResponseDirectionConfig response_direction_config = 8;
 
-  // If true, chooses this compressor first to do compression when the q-values in `Accept-Encoding` are same.
+  // If true, chooses this compressor first to do compression when the q-values in ``Accept-Encoding`` are same.
   // The last compressor which enables choose_first will be chosen if multiple compressor filters in the chain have choose_first as true.
   bool choose_first = 9;
 }
 
-// Per-route overrides of `ResponseDirectionConfig`. Anything added here should be optional,
+// Per-route overrides of ``ResponseDirectionConfig``. Anything added here should be optional,
 // to allow overriding arbitrary subsets of configuration. Omitted fields must have no affect.
 message ResponseDirectionOverrides {
 }
 
 // Per-route overrides. As per-route overrides are needed, they should be
-// added here, mirroring the structure of `Compressor`. All fields should be
+// added here, mirroring the structure of ``Compressor``. All fields should be
 // optional, to allow overriding arbitrary subsets of configuration.
 message CompressorOverrides {
   // If present, response compression is enabled.
@@ -152,7 +152,7 @@ message CompressorPerRoute {
     // Overrides Compressor.runtime_enabled and CommonDirectionConfig.enabled.
     bool disabled = 1 [(validate.rules).bool = {const: true}];
 
-    // Per-route overrides. Fields set here will override corresponding fields in `Compressor`.
+    // Per-route overrides. Fields set here will override corresponding fields in ``Compressor``.
     CompressorOverrides overrides = 2;
   }
 }

api/envoy/extensions/filters/http/geoip/v3/geoip.proto

@@ -77,7 +77,7 @@ message Geoip {
   }
 
   // If set, the :ref:`xff_num_trusted_hops <envoy_v3_api_field_extensions.filters.http.geoip.v3.Geoip.XffConfig.xff_num_trusted_hops>` field will be used to determine
-  // trusted client address from `x-forwarded-for` header.
+  // trusted client address from ``x-forwarded-for`` header.
   // Otherwise, the immediate downstream connection source address will be used.
   // [#next-free-field: 2]
   XffConfig xff_config = 1;

api/envoy/extensions/filters/http/grpc_field_extraction/v3/config.proto

@@ -140,14 +140,14 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 message GrpcFieldExtractionConfig {
   // The proto descriptor set binary for the gRPC services.
   //
-  // It could be passed by a local file through `Datasource.filename` or embedded in the
-  // `Datasource.inline_bytes`.
+  // It could be passed by a local file through ``Datasource.filename`` or embedded in the
+  // ``Datasource.inline_bytes``.
   config.core.v3.DataSource descriptor_set = 1 [(validate.rules).message = {required: true}];
 
   // Specify the extraction info.
   // The key is the fully qualified gRPC method name.
-  // `${package}.${Service}.${Method}`, like
-  // `endpoints.examples.bookstore.BookStore.GetShelf`
+  // ``${package}.${Service}.${Method}``, like
+  // ``endpoints.examples.bookstore.BookStore.GetShelf``
   //
   // The value is the field extractions for individual gRPC method.
   map<string, FieldExtractions> extractions_by_method = 2;
@@ -158,8 +158,8 @@ message GrpcFieldExtractionConfig {
 message FieldExtractions {
   // The field extractions for requests.
   // The key is the field path within the grpc request.
-  // For example, we can define `foo.bar.name` if we want to extract
-  // Request.foo.bar.name.
+  // For example, we can define ``foo.bar.name`` if we want to extract
+  // ``Request.foo.bar.name``.
   //
   // .. code-block:: proto
   //

api/envoy/extensions/filters/http/json_to_metadata/v3/json_to_metadata.proto

@@ -99,9 +99,9 @@ message JsonToMetadata {
     repeated Rule rules = 1 [(validate.rules).repeated = {min_items: 1}];
 
     // Allowed content-type for json to metadata transformation.
-    // Default to {"application/json"}.
+    // Default to ``{"application/json"}``.
     //
-    // Set `allow_empty_content_type` if empty/missing content-type header
+    // Set ``allow_empty_content_type`` if empty/missing content-type header
     // is allowed.
     repeated string allow_content_types = 2
         [(validate.rules).repeated = {items {string {min_len: 1}}}];

api/envoy/extensions/filters/http/jwt_authn/v3/config.proto

@@ -270,8 +270,8 @@ message JwtProvider {
   //
   string header_in_metadata = 14;
 
-  // If non empty, the failure status `::google::jwt_verify::Status` for a non verified JWT will be written to StreamInfo DynamicMetadata
-  // in the format as: ``namespace`` is the jwt_authn filter name as ````envoy.filters.http.jwt_authn````
+  // If non empty, the failure status ``::google::jwt_verify::Status`` for a non verified JWT will be written to StreamInfo DynamicMetadata
+  // in the format as: ``namespace`` is the jwt_authn filter name as ``envoy.filters.http.jwt_authn``
   // The value is the ``protobuf::Struct``. The values of this field will be ``code`` and ``message``
   // and they will contain the JWT authentication failure status code and a message describing the failure.
   //

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

@@ -382,7 +382,7 @@ message HttpConnectionManager {
     // on stream close, when the HTTP request is complete. If this field is set, the HCM will flush access
     // logs periodically at the specified interval. This is especially useful in the case of long-lived
     // requests, such as CONNECT and Websockets. Final access logs can be detected via the
-    // `requestComplete()` method of `StreamInfo` in access log filters, or thru the `%DURATION%` substitution
+    // ``requestComplete()`` method of ``StreamInfo`` in access log filters, or through the ``%DURATION%`` substitution
     // string.
     // The interval must be at least 1 millisecond.
     google.protobuf.Duration access_log_flush_interval = 1
@@ -883,12 +883,12 @@ message HttpConnectionManager {
   // [#extension-category: envoy.http.header_validators]
   config.core.v3.TypedExtensionConfig typed_header_validation_config = 50;
 
-  // Append the `x-forwarded-port` header with the port value client used to connect to Envoy. It
-  // will be ignored if the `x-forwarded-port` header has been set by any trusted proxy in front of Envoy.
+  // Append the ``x-forwarded-port`` header with the port value client used to connect to Envoy. It
+  // will be ignored if the ``x-forwarded-port`` header has been set by any trusted proxy in front of Envoy.
   bool append_x_forwarded_port = 51;
 
-  // Whether the HCM will add ProxyProtocolFilterState to the Connection lifetime filter state. Defaults to `true`.
-  // This should be set to `false` in cases where Envoy's view of the downstream address may not correspond to the
+  // Whether the HCM will add ProxyProtocolFilterState to the Connection lifetime filter state. Defaults to ``true``.
+  // This should be set to ``false`` in cases where Envoy's view of the downstream address may not correspond to the
   // actual client address, for example, if there's another proxy in front of the Envoy.
   google.protobuf.BoolValue add_proxy_protocol_connection_state = 53;
 }

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

@@ -43,7 +43,7 @@ message ZooKeeperProxy {
   google.protobuf.UInt32Value max_packet_bytes = 3;
 
   // Whether to emit latency threshold metrics. If not set, it defaults to false.
-  // If false, setting `default_latency_threshold` and `latency_threshold_overrides` will not have effect.
+  // If false, setting ``default_latency_threshold`` and ``latency_threshold_overrides`` will not have effect.
   bool enable_latency_threshold_metrics = 4;
 
   // The default latency threshold to decide the fast/slow responses and emit metrics (used for error budget calculation).

api/envoy/extensions/http/custom_response/local_response_policy/v3/local_response_policy.proto

@@ -26,11 +26,11 @@ option (xds.annotations.v3.file_status).work_in_progress = true;
 // downstream.
 message LocalResponsePolicy {
   // Optional new local reply body text. It will be used
-  // in the `%LOCAL_REPLY_BODY%` command operator in the `body_format`.
+  // in the ``%LOCAL_REPLY_BODY%`` command operator in the ``body_format``.
   config.core.v3.DataSource body = 1;
 
-  // Optional body format to be used for this response. If `body_format` is  not
-  // provided, and `body` is, the contents of `body` will be used to populate
+  // Optional body format to be used for this response. If ``body_format`` is  not
+  // provided, and ``body`` is, the contents of ``body`` will be used to populate
   // the body of the local reply without formatting.
   config.core.v3.SubstitutionFormatString body_format = 2;
 

api/envoy/extensions/http/custom_response/redirect_policy/v3/redirect_policy.proto

@@ -43,12 +43,12 @@ message RedirectPolicy {
     string uri = 1 [(validate.rules).string = {min_len: 1}];
 
     // Specify elements of the redirect url individually.
-    // Note: Do not specify the `response_code` field in `redirect_action`, use
-    // `status_code` instead.
-    // The following fields in `redirect_action` are currently not supported,
+    // Note: Do not specify the ``response_code`` field in ``redirect_action``, use
+    // ``status_code`` instead.
+    // The following fields in ``redirect_action`` are currently not supported,
     // and specifying them will cause the config to be rejected:
-    // - `prefix_rewrite`
-    // - `regex_rewrite`
+    // - ``prefix_rewrite``
+    // - ``regex_rewrite``
     config.route.v3.RedirectAction redirect_action = 2;
   }
 

api/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto

@@ -30,18 +30,18 @@ message LeastRequest {
   // The following formula is used to calculate the dynamic weights when hosts have different load
   // balancing weights:
   //
-  // `weight = load_balancing_weight / (active_requests + 1)^active_request_bias`
+  // ``weight = load_balancing_weight / (active_requests + 1)^active_request_bias``
   //
   // The larger the active request bias is, the more aggressively active requests will lower the
   // effective weight when all host weights are not equal.
   //
-  // `active_request_bias` must be greater than or equal to 0.0.
+  // ``active_request_bias`` must be greater than or equal to 0.0.
   //
-  // When `active_request_bias == 0.0` the Least Request Load Balancer doesn't consider the number
+  // When ``active_request_bias == 0.0`` the Least Request Load Balancer doesn't consider the number
   // of active requests at the time it picks a host and behaves like the Round Robin Load
   // Balancer.
   //
-  // When `active_request_bias > 0.0` the Least Request Load Balancer scales the load balancing
+  // When ``active_request_bias > 0.0`` the Least Request Load Balancer scales the load balancing
   // weight by the number of active requests at the time it does a pick.
   //
   // The value is cached for performance reasons and refreshed whenever one of the Load Balancer's

api/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto

@@ -53,7 +53,7 @@ message RingHash {
   // :ref:`minimum_ring_size<envoy_v3_api_field_config.cluster.v3.Cluster.RingHashLbConfig.minimum_ring_size>`.
   google.protobuf.UInt64Value maximum_ring_size = 3 [(validate.rules).uint64 = {lte: 8388608}];
 
-  // If set to `true`, the cluster will use hostname instead of the resolved
+  // If set to ``true``, the cluster will use hostname instead of the resolved
   // address as the key to consistently hash to an upstream host. Only valid for StrictDNS clusters with hostnames which resolve to a single IP address.
   //
   // .. note::
@@ -68,15 +68,15 @@ message RingHash {
   // Minimum is 100.
   //
   // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified
-  // `hash_balance_factor`, requests to any upstream host are capped at `hash_balance_factor/100` times the average number of requests
+  // ``hash_balance_factor``, requests to any upstream host are capped at ``hash_balance_factor/100`` times the average number of requests
   // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing
   // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify
   // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the
   // cascading overflow effect when choosing the next host in the ring/table).
   //
   // If weights are specified on the hosts, they are respected.
   //
-  // This is an O(N) algorithm, unlike other load balancers. Using a lower `hash_balance_factor` results in more hosts
+  // This is an O(N) algorithm, unlike other load balancers. Using a lower ``hash_balance_factor`` results in more hosts
   // being probed, so use a higher value if you require better performance.
   //
   // .. note::