proto2asciidoc is a protoc plugin that generates asciidoc documentation from the Protobuffer IDL files.
The goal of the project was to prevent API documentation inconsistenties between the actual API and the docs. By generating the code from the Protobuf definition the documentation is always in sync.
The current version is a plugin, which is a from scratch rewrite of the previous one that generated asciidoc too but parsed the Protobuffer files itself.
Can be used in conjunction with code2asciidoc to produce even more consistent API documentation.
The following options for the plugin can be passed to protoc, the default for everything is off. Ensure the options are comma separated.
Example
--proto2asciidoc_opt=rest=on,sorted=onAll boolean values are either on or off
| Option | Accepted Value | Description |
| extension | boolean | Enables the optional Ruby asciidoctor extension for more stylized hyperlinks |
| collapsible | boolean | When enabled the tables produced are collapsible through HTML |
| rest | boolean | Output the REST information for the Service endpoints too |
| icons | boolean | Instead of string for true and false asciidoc icons are used |
| sorted | boolean | When enabled the Services, Enum and Messages are sorted alphabetically vs the |
order they appear in the file in. |
This tool assumes the extension in asciidoc/extension will be loaded when using
AsciiDoctor.
The following snippet can be used inside a Makefile.
Of course you have to ensure that the directory is in a location your Makefile can find it.
Makefile
# Asciidoctor settings
ASCIIDOC_EXT := -r ./asciidoctor/extensions/proto2asciidoc-inline-macro.rbThe following shows how the README (if on Github) you’re currently reading has been produced.
Optional formats
markdown:
@asciidoctor ${ASCIIDOC_EXT} docs/readme.adoc -b docbook -a leveloffset=+1 -o - | pandoc --markdown-headings=atx --wrap=preserve -t gfm -f docbook - > README.md
go get github.com/productsupcom/protoc-gen-proto2asciidoc/cmd/protoc-gen-proto2asciidoc