Generate agent configuration reference documentation from the proto file
Goal
Provide an easy to navigate reference documentation for the Agent configuration.
This way we can have a single place to document the configuration reference. At the same time, we can write easier to navigate documentation manually that can refer the user to this reference.
Proposal
Use https://github.com/pseudomuto/protoc-gen-doc to generate the documentation as part of a release.
protoc-gen-doc
can generate markdown documentation too, so we can include it in the official GitLab documentation automatically or we can generate it as HTML and host it on GitLab pages.
We should store up-to-date markdown docs in the agent repo and copy them into the GitLab docs repo each time we bump the version there. We'd need to update our release process doc to remember to do that each time.
That way we'll have docs for the in-development version and docs for a concrete release.
We only need docs for public-facing proto files, which are agentcfg.proto
and kascfg.proto
. Those files already have some comments. They may need to be re-formatted to be recognized as docs by the plugin.
We use rules_proto_grpc
to general stuff from proto files. rules_proto_grpc
already has support for this protoc plugin. We should use that.
Example
Copy https://github.com/envoyproxy/protoc-gen-validate/blob/main/validate/validate.proto into vendor-protos/validate
, and run
docker run --rm \
-v ${pwd}/doc:/out \
-v ${pwd}pkg/agentcfg:/protos \
-v ${pwd}/vendor-protos:/vendored
pseudomuto/protoc-gen-doc -I /vendored agentcfg.proto --doc_opt=markdown,docs.md
this will output a doc/docs.md
file. To generate html, remove the --doc_opt
option.