Introduction to protoc-gen-doc
protoc-gen-doc is a powerful documentation generator plugin designed for the Google Protocol Buffers compiler, also known as protoc. This tool facilitates the creation of various types of documentation from the comments in .proto files, which are used in defining message structures in Protocol Buffers. With protoc-gen-doc, developers can easily generate documentation in formats like HTML, JSON, DocBook, and Markdown.
Compatibility and Support
The plugin supports both proto2 and proto3 versions and is flexible enough to handle both formats simultaneously in the same project environment.
Installation
protoc-gen-doc can be installed in several ways to suit different needs and environments:
-
Docker Image: A ready-to-use Docker image is available, which can be pulled using the command
docker pull pseudomuto/protoc-gen-doc. This option ensures you have all necessary components to generate documentation conveniently. -
Go Installation: For those preferring a local setup, the plugin can be obtained via Go by running
go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest. -
Pre-built Releases: Precompiled binaries suitable for various platforms can be downloaded from the project's releases page on GitHub.
-
Maven Central: The plugin is also accessible through Maven Central for integration in Java-based projects, as detailed in the gradle example provided in the documentation.
Using the Plugin
To use the plugin, one must pass the --doc_out and --doc_opt options to the protoc compiler. The format allows specifying the documentation format and the output file name, with the possibility to designate custom Go templates for tailored documentation needs.
Recommended Usage with Docker
The Docker image method is considered the most user-friendly, offering organized volume mounting for output and proto files. For instance, to generate HTML documentation for proto files, the following Docker command can be used:
docker run --rm \
-v $(pwd)/examples/doc:/out \
-v $(pwd)/examples/proto:/protos \
pseudomuto/protoc-gen-doc
This command outputs HTML files by default to the specified directory. Parameters can be adjusted to change the output format and destination files.
Simple Usage in CLI
For those who prefer command-line interfaces, generating documentation without Docker can also be straightforward. An example command to create HTML documentation is:
protoc --doc_out=./doc --doc_opt=html,index.html proto/*.proto
This requires the plugin executable to be in the PATH.
Customization
Users with specific format requirements can create and use custom templates by pointing to a template file when running the plugin. This flexibility allows for customization of both functionality and aesthetics, including stylesheet adjustments for HTML output.
Writing and Excluding Documentation
protoc-gen-doc processes comments from proto files, supporting leading and trailing comments for documentation purposes. Developers can also exclude certain comments from documentation by using the @exclude prefix, allowing precise control over what gets included in the final output.
Example Outputs
The plugin has been demonstrated to produce various output formats from example proto files like Booking.proto and Vehicle.proto. These examples show the capabilities of generating Markdown, HTML, DocBook, and JSON documents.
Conclusion
protoc-gen-doc is a versatile and robust solution for generating documentation from Protocol Buffers files, supporting multiple formats and offering installation flexibility. It suits a wide range of development environments, from localized setups to containerized applications, empowering developers to maintain comprehensive and easily accessible documentation.