Automatically generate protobuf documentation (#946)

Signed-off-by: Cody Littley <[email protected]>

Makefile

@@ -33,6 +33,7 @@ clean:
 # Builds the protobuf files inside a docker container.
 protoc: clean
 	./api/builder/protoc-docker.sh
+	./api/builder/generate-docs.sh
 
 # Builds the protobuf files locally (i.e. without docker).
 protoc-local: clean

api/builder/generate-docs.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+
+# This script generates protobuf documentation.
+
+# The location where this script can be found.
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+API_DIR="${SCRIPT_DIR}/.."
+PROTO_DIR="${API_DIR}/proto"
+DOCS_DIR="${API_DIR}/docs"
+
+# Function to get the relative path of file in argument 1 with respect directory in argument 2.
+# Doesn't use the convenient 'realpath --relative-to' because it's not available on macOS.
+relativePath() {
+ python3 -c 'import os.path, sys; print(os.path.relpath(sys.argv[1],sys.argv[2]))' "${1}" "${2}"
+}
+
+# Find all .proto files.
+PROTO_FILES=( $(find "${PROTO_DIR}" -name '*.proto') )
+
+# Make the proto files relative to the proto directory.
+for i in "${!PROTO_FILES[@]}"; do
+    PROTO_FILES[$i]=$(relativePath "${PROTO_FILES[$i]}" "${PROTO_DIR}")
+done
+
+# Sort the proto files alphabetically. Required for deterministic output.
+IFS=$'\n' PROTO_FILES=($(sort <<<"${PROTO_FILES[*]}")); unset IFS
+
+# Generate unified HTML doc
+echo "Generating unified HTML documentation..."
+docker run --rm \
+  -v "${DOCS_DIR}":/out \
+  -v "${PROTO_DIR}":/protos \
+  pseudomuto/protoc-gen-doc \
+  "${PROTO_FILES[@]}" \
+  --doc_opt=html,eigenda-protos.html 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  echo "Failed to generate unified HTML documentation."
+  exit 1
+fi
+
+# Generate unified markdown doc
+echo "Generating unified markdown documentation..."
+docker run --rm \
+  -v "${DOCS_DIR}":/out \
+  -v "${PROTO_DIR}":/protos \
+  pseudomuto/protoc-gen-doc \
+  "${PROTO_FILES[@]}" \
+  --doc_opt=markdown,eigenda-protos.md 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  echo "Failed to generate unified markdown documentation."
+  exit 1
+fi
+
+# Generate individual markdown/HTML docs
+for PROTO_FILE in "${PROTO_FILES[@]}"; do
+  PROTO_NAME=$(basename "${PROTO_FILE}" .proto)
+
+  echo "Generating markdown documentation for ${PROTO_NAME}..."
+  docker run --rm \
+    -v "${DOCS_DIR}":/out \
+    -v "${PROTO_DIR}":/protos \
+    pseudomuto/protoc-gen-doc \
+    "${PROTO_FILE}" \
+    --doc_opt=markdown,"${PROTO_NAME}.md" 2>/dev/null
+
+  if [ $? -ne 0 ]; then
+    echo "Failed to generate documentation for ${PROTO_NAME}."
+    exit 1
+  fi
+
+  echo "Generating HTML documentation for ${PROTO_NAME}..."
+  docker run --rm \
+    -v "${DOCS_DIR}":/out \
+    -v "${PROTO_DIR}":/protos \
+    pseudomuto/protoc-gen-doc \
+    "${PROTO_FILE}" \
+    --doc_opt=html,"${PROTO_NAME}.html" 2>/dev/null
+
+  if [ $? -ne 0 ]; then
+    echo "Failed to generate documentation for ${PROTO_NAME}."
+    exit 1
+  fi
+done

api/builder/is-repo-clean.sh

@@ -10,5 +10,6 @@ if output=$(git status --porcelain) && [ -z "$output" ]; then
 else
   echo "Repository is dirty:"
   git status
+  git diff
   exit 1
 fi

api/docs/README.md

@@ -1,6 +1,7 @@
-This folder contains the API documentation for the gRPC services included in the EigenDA platform. Each markdown file contains the protobuf definitions for each respective service including:
-- Churner: a hosted service responsible for maintaining the active set of Operators in the EigenDA network based on their delegated TVL.
-- Disperser: the hosted service and primary point of interaction for Rollup users.
-- Node: individual EigenDA nodes run on the network by EigenLayer Operators.
-- Retriever: a service that users can run on their own infrastructure, which exposes a gRPC endpoint for retrieval of blobs from EigenDA nodes.
+This directory contains documentation for protobufs in the `api/proto/` directory. The documentation is in several
+formats, depending on the needs of the reader.
 
+- [eigenda-protos.hml](./eigenda-protos.html): An HTML file containing the documentation for all the protobufs in the `api/proto/` directory.
+- [eigenda-protos.md](./eigenda-protos.md): A markdown file containing the documentation for all the protobufs in the `api/proto/` directory.
+- PROTO-NAME.html: An HTML file containing the documentation for a specific protobuf in the `api/proto/` directory.
+- PROTO-NAME.md: A markdown file containing the documentation for a specific protobuf in the `api/proto/` directory.