Generate reference docs from proto files

Integrates `gen-proto-docs` into the project such that when generating
Rust code from the protos, the reference documentation is generated at
the same time.

Closes #981

build/Makefile

@@ -131,7 +131,7 @@ build: binary-archive build-image
 # Build all binaries
 build-all-binaries: ensure-build-image build-linux-binary build-macos-binary build-windows-binary
 
-# Checks for changes to protobuf definitions and generates rust code if there is any.
+# Checks for changes to protobuf definitions and generates rust code and reference documentation if there is any.
 gen-protobuf: ensure-build-image
 	docker run --rm $(DOCKER_RUN_ARGS) $(common_rust_args) \
 		--entrypoint=cargo $(BUILD_IMAGE_TAG) run -p proto-gen -- generate

build/README.md

@@ -39,14 +39,16 @@ To build a production release, run:
 
 ##### Generating Protobuf Files
 
-If you are adding or editing the `.proto` files in this repository, they will need to be regenerated. To do this,
-you will need [protoc](https://grpc.io/docs/protoc-installation/) installed locally.
+If you are adding or editing the `.proto` files in this repository, they will need to be regenerated along with the 
+reference documentation. To do this,
+you will need [protoc](https://grpc.io/docs/protoc-installation/) and 
+[protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) installed locally.
 
 Then run:
 
 `cargo run -p proto-gen -- generate`
 
-Which will identify changes in protobuf definitions and regenerate code appropriately. 
+Which will identify changes in protobuf definitions and regenerate code and documentation appropriately. 
 
 #### Testing
 

build/build-image/Dockerfile

@@ -30,6 +30,13 @@ RUN set -eux && \
     npm install -g browser-sync && \
     echo "source /etc/bash_completion" >> /root/.bashrc
 
+# install protoc-gen-doc
+RUN cd /tmp && \
+    wget --quiet -O protoc-gen-doc.tar.gz https://github.com/pseudomuto/protoc-gen-doc/releases/download/v1.5.1/protoc-gen-doc_1.5.1_linux_amd64.tar.gz && \
+    tar -xf protoc-gen-doc.tar.gz && \
+    mv ./protoc-gen-doc /usr/local/bin/ && \
+    rm protoc-gen-doc.tar.gz
+
 # install gcloud
 # Credit: https://cloud.google.com/sdk/docs/install#deb
 RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key --keyring /usr/share/keyrings/cloud.google.gpg  add - && apt-get update -y && \
@@ -75,6 +82,7 @@ RUN set -eux; \
     cargo install --locked cargo-about && \
     cargo install --locked mdbook-variables && \
     cargo install --locked cargo-deny && \
+    cargo install --locked proto-gen && \
     rustup --version && \
     cargo --version && \
     rustc --version

crates/proto-gen/gen.rs

@@ -91,15 +91,13 @@ fn install() {
         if !child.wait().expect("tar is not installed").success() {
             panic!("failed to extract proto-gen binary from tarball");
         }
-    } else {
-        if !Command::new("cargo")
-            .args(["install", "--locked", "-f", "proto-gen"])
-            .status()
-            .expect("cargo not installed")
-            .success()
-        {
-            panic!("failed to install proto-gen via cargo");
-        }
+    } else if !Command::new("cargo")
+        .args(["install", "--locked", "-f", "proto-gen"])
+        .status()
+        .expect("cargo not installed")
+        .success()
+    {
+        panic!("failed to install proto-gen via cargo");
     }
 }
 
@@ -226,6 +224,50 @@ fn execute(which: &str) {
     if !cmd.status().expect("proto-gen was not installed").success() {
         panic!("proto-gen {which} failed");
     }
+
+    if which == "generate" {
+        docs(files);
+    }
+}
+
+fn docs(files: &[(&str, &[&str])]) {
+    let mut cmd = Command::new("protoc");
+
+    let quilkin_protos: Vec<&(&str, &[&str])> = files
+        .iter()
+        .filter(|item| item.0 == "proto/quilkin")
+        .collect();
+    let includes: Vec<&(&str, &[&str])> = files
+        .iter()
+        .filter(|item| item.0 != "proto/quilkin")
+        .collect();
+
+    for (dir, files) in includes {
+        if files.is_empty() {
+            cmd.args(["-I", dir]);
+        } else {
+            for file in *files {
+                cmd.args(["-I".into(), format!("{dir}/{file}.proto")]);
+            }
+        }
+    }
+
+    cmd.args(["--doc_out", "./docs/src/services/xds"]);
+    cmd.args(["--doc_opt", "markdown,protos.md"]);
+
+    for (dir, files) in quilkin_protos {
+        for file in *files {
+            cmd.arg(format!("{dir}/{file}.proto"));
+        }
+    }
+
+    if !cmd
+        .status()
+        .expect("protoc-gen-doc was not installed")
+        .success()
+    {
+        panic!("protoc-gen-doc failed");
+    }
 }
 
 fn copy() {
@@ -294,7 +336,7 @@ fn copy() {
     ];
 
     let args: Vec<_> = std::env::args().skip(2).collect();
-    let name = args.get(0).expect("must provide source name");
+    let name = args.first().expect("must provide source name");
     let path = args.get(1).expect("must provide path");
 
     let Some(ri) = REPOS.iter().find(|r| r.name == name) else {

docs/src/SUMMARY.md

@@ -37,7 +37,7 @@
     - [Providers]()
         - [Agones](./services/xds/providers/agones.md)
         - [Filesystem](./services/xds/providers/filesystem.md)
-
+    - [Protobuf Reference](./services/xds/protos.md)
 ---
 
 - [Relay](./services/relay.md)