docs: reorganize for readability (#457)

I went through and reorganized things to make the v2 docs more
human browsable. I also did a few misc cleanups. There is a lot
more to do here which I'm hoping to find a contractor to pay to
work on, but this is a step in the right direction.

Signed-off-by: Matt Klein <mklein@lyft.com>

docs/root/api-v2/api.rst

@@ -7,27 +7,9 @@ v2 API reference
   :glob:
   :maxdepth: 2
 
-  config/bootstrap/v2/bootstrap.proto
-  api/v2/core/config_source.proto
-  api/v2/core/grpc_service.proto
-  api/v2/lds.proto
-  api/v2/listener/listener.proto
-  api/v2/cds.proto
-  api/v2/cluster/outlier_detection.proto
-  api/v2/cluster/circuit_breaker.proto
-  api/v2/endpoint/endpoint.proto
-  api/v2/eds.proto
-  api/v2/core/health_check.proto
-  api/v2/route/route.proto
-  api/v2/rds.proto
-  api/v2/auth/cert.proto
-  config/metrics/v2/stats.proto
-  config/metrics/v2/metrics_service.proto
-  config/trace/v2/trace.proto
-  api/v2/core/base.proto
-  api/v2/core/address.proto
-  api/v2/core/protocol.proto
-  api/v2/discovery.proto
-  api/v2/ratelimit/ratelimit.proto
-  config/ratelimit/v2/rls.proto
+  bootstrap/bootstrap
+  listeners/listeners
+  clusters/clusters
+  http_routes/http_routes
   config/filter/filter
+  common_messages/common_messages

docs/root/api-v2/bootstrap/bootstrap.rst

@@ -0,0 +1,12 @@
+Bootstrap
+=========
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../config/bootstrap/v2/bootstrap.proto
+  ../config/metrics/v2/stats.proto
+  ../config/metrics/v2/metrics_service.proto
+  ../config/ratelimit/v2/rls.proto
+  ../config/trace/v2/trace.proto

docs/root/api-v2/clusters/clusters.rst

@@ -0,0 +1,13 @@
+Clusters
+========
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../api/v2/cds.proto
+  ../api/v2/cluster/outlier_detection.proto
+  ../api/v2/cluster/circuit_breaker.proto
+  ../api/v2/endpoint/endpoint.proto
+  ../api/v2/eds.proto
+  ../api/v2/core/health_check.proto

docs/root/api-v2/common_messages/common_messages.rst

@@ -0,0 +1,15 @@
+Common messages
+===============
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../api/v2/core/base.proto
+  ../api/v2/core/address.proto
+  ../api/v2/core/protocol.proto
+  ../api/v2/discovery.proto
+  ../api/v2/core/config_source.proto
+  ../api/v2/core/grpc_service.proto
+  ../api/v2/auth/cert.proto
+  ../api/v2/ratelimit/ratelimit.proto

docs/root/api-v2/http_routes/http_routes.rst

@@ -0,0 +1,9 @@
+HTTP route management
+=====================
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../api/v2/rds.proto
+  ../api/v2/route/route.proto

docs/root/api-v2/listeners/listeners.rst

@@ -0,0 +1,9 @@
+Listeners
+=========
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../api/v2/lds.proto
+  ../api/v2/listener/listener.proto

envoy/api/v2/core/address.proto

@@ -10,7 +10,6 @@ import "gogoproto/gogo.proto";
 option (gogoproto.equal_all) = true;
 
 // [#protodoc-title: Network addresses]
-// [#v2-api-diff: Addresses now have .proto structure.]
 
 message Pipe {
   // Unix Domain Socket path.

envoy/api/v2/lds.proto

@@ -15,7 +15,8 @@ import "gogoproto/gogo.proto";
 
 option (gogoproto.equal_all) = true;
 
-// [#protodoc-title: LDS]
+// [#protodoc-title: Listener]
+// Listener :ref:`configuration overview <config_listeners>`
 
 // The Envoy instance initiates an RPC at startup to discover a list of
 // listeners. Updates are delivered via streaming from the LDS server and

envoy/api/v2/listener/listener.proto

@@ -15,7 +15,7 @@ import "gogoproto/gogo.proto";
 
 option (gogoproto.equal_all) = true;
 
-// [#protodoc-title: Listeners]
+// [#protodoc-title: Listener components]
 // Listener :ref:`configuration overview <config_listeners>`
 
 message Filter {

envoy/api/v2/rds.proto

@@ -13,7 +13,9 @@ import "gogoproto/gogo.proto";
 
 option (gogoproto.equal_all) = true;
 
-// [#protodoc-title: RDS]
+// [#protodoc-title: HTTP route configuration]
+// * Routing :ref:`architecture overview <arch_overview_http_routing>`
+// * HTTP :ref:`router filter <config_http_filters_router>`
 
 // The resource_names field in DiscoveryRequest specifies a route configuration.
 // This allows an Envoy configuration with multiple HTTP listeners (and

envoy/api/v2/route/route.proto

@@ -14,8 +14,7 @@ import "gogoproto/gogo.proto";
 
 option (gogoproto.equal_all) = true;
 
-// [#protodoc-title: HTTP route management]
-
+// [#protodoc-title: HTTP route]
 // * Routing :ref:`architecture overview <arch_overview_http_routing>`
 // * HTTP :ref:`router filter <config_http_filters_router>`
 

envoy/config/bootstrap/v2/bootstrap.proto

@@ -67,6 +67,7 @@ message Bootstrap {
     // streamed on the ADS channel.
     envoy.api.v2.core.ApiConfigSource ads_config = 3;
 
+    // [#not-implemented-hide:] Hide from docs.
     message DeprecatedV1 {
       // This is the global :ref:`SDS <arch_overview_dynamic_config_sds>` config
       // when using v1 REST for :ref:`CDS
@@ -75,7 +76,7 @@ message Bootstrap {
       envoy.api.v2.core.ConfigSource sds_config = 1;
     }
 
-    // [#not-implemented-hide:]
+    // [#not-implemented-hide:] Hide from docs.
     DeprecatedV1 deprecated_v1 = 4 [deprecated = true];
   }
   // xDS configuration sources.

envoy/config/filter/accesslog/v2/accesslog.proto

@@ -26,7 +26,6 @@ import "gogoproto/gogo.proto";
 // in their name.
 
 // Defines fields that are shared by all Envoy access logs.
-// [#proto-status: draft]
 // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
 message AccessLogCommon {
   // This field indicates the rate at which this log entry was sampled.
@@ -110,7 +109,6 @@ message AccessLogCommon {
   envoy.api.v2.core.Metadata metadata = 17;
 }
 
-// [#proto-status: draft]
 // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
 // Flags indicating occurences during request/response processing.
 message ResponseFlags {
@@ -151,7 +149,6 @@ message ResponseFlags {
   bool rate_limited = 12;
 }
 
-// [#proto-status: draft]
 // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
 // Properties of a negotiated TLS connection.
 message TLSProperties {
@@ -176,14 +173,12 @@ message TLSProperties {
   string tls_sni_hostname = 3;
 }
 
-// [#proto-status: draft]
 // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
 message TCPAccessLogEntry {
   // Common properties shared by all Envoy access logs.
   AccessLogCommon common_properties = 1;
 }
 
-// [#proto-status: draft]
 // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
 message HTTPRequestProperties {
   // The request method (RFC 7231/2616).
@@ -239,7 +234,6 @@ message HTTPRequestProperties {
   map<string, string> request_headers = 13;
 }
 
-// [#proto-status: draft]
 // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
 message HTTPResponseProperties {
   // The HTTP response code returned by Envoy.
@@ -261,7 +255,6 @@ message HTTPResponseProperties {
   map<string, string> response_headers = 4;
 }
 
-// [#proto-status: draft]
 // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
 message HTTPAccessLogEntry {
   // Common properties shared by all Envoy access logs.

envoy/config/metrics/v2/metrics_service.proto

@@ -1,8 +1,6 @@
 syntax = "proto3";
 
-// [#proto-status: draft]
-
-// [#protodoc-title: Metrics Service]
+// [#protodoc-title: Metrics service]
 
 package envoy.config.metrics.v2;
 

envoy/config/ratelimit/v2/rls.proto

@@ -7,7 +7,7 @@ import "envoy/api/v2/core/grpc_service.proto";
 
 import "validate/validate.proto";
 
-// [#protodoc-title: Rate limit service configuration]
+// [#protodoc-title: Rate limit service]
 
 // Rate limit :ref:`configuration overview <config_rate_limit_service>`.
 message RateLimitServiceConfig {