gendoc

README

protoc-gen-doc

This is a documentation generator plugin for the Google Protocol Buffers compiler (protoc). The plugin can generate HTML, JSON, DocBook and Markdown documentation from comments in your .proto files.

It supports proto2 and proto3, and can handle having both in the same context (see examples for proof).

Installation

There is a Docker image available (docker pull pseudomuto/protoc-gen-doc) that has everything you need to generate documentation from your protos.

If you'd like to install this locally, you can go get it.

go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc

Invoking the Plugin

The plugin is invoked by passing the --doc_out, and --doc_opt options to the protoc compiler. The option has the following format:

--doc_opt=<FORMAT>|<TEMPLATE_FILENAME>,<OUT_FILENAME>

The format may be one of the built-in ones ( docbook, html, markdown or json) or the name of a file containing a custom Go template.

Using the Docker Image (Recommended)

The docker image has two volumes: /out and /protos which are the directory to write the documentation to and the directory containing your proto files.

You could generate HTML docs for the examples by running the following:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  pseudomuto/protoc-gen-doc

By default HTML documentation is generated in /out/index.html for all .proto files in the /protos volume. This can be changed by passing the --doc_opt parameter to the container.

For example, to generate Markdown for all the examples:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  pseudomuto/protoc-gen-doc --doc_opt=markdown,docs.md

You can also generate documentation for a single file. This can be done by passing the file(s) to the command:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  pseudomuto/protoc-gen-doc --doc_opt=markdown,docs.md /protos/Booking.proto [OPTIONALLY LIST MORE FILES]

You can also exclude proto files that match specific path expressions. This is done by passing a second option delimited by :. For example, you can pass any number of comma separated patterns as the second option:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  pseudomuto/protoc-gen-doc --doc_opt=:google/*,somepath/*

Remember: Paths should be from within the container, not the host!

NOTE: Due to the way wildcard expansion works with docker you cannot use a wildcard path (e.g. protos/*.proto) in the file list. To get around this, if no files are passed, the container will generate docs for protos/*.proto, which can be changed by mounting different volumes.

Simple Usage

For example, to generate HTML documentation for all .proto files in the proto directory into doc/index.html, type:

protoc --doc_out=./doc --doc_opt=html,index.html proto/*.proto

The plugin executable must be in PATH for this to work.

Using a precompiled binary

Alternatively, you can specify a pre-built/not in PATH binary using the --plugin option.

protoc \
  --plugin=protoc-gen-doc=./protoc-gen-doc \
  --doc_out=./doc \
  --doc_opt=html,index.html \
  proto/*.proto

With a Custom Template

If you'd like to use your own template, simply use the path to the template file rather than the type.

protoc --doc_out=./doc --doc_opt=/path/to/template.tmpl,index.txt proto/*.proto

For information about the available template arguments and functions, see Custom Templates. If you just want to customize the look of the HTML output, put your CSS in stylesheet.css next to the output file and it will be picked up.

Writing Documentation

Messages, Fields, Services (and their methods), Enums (and their values), Extensions, and Files can be documented. Generally speaking, comments come in 2 forms: leading and trailing.

Leading comments

Leading comments can be used everywhere.

/**
 * This is a leading comment for a message
*/
message SomeMessage {
  // this is another leading comment
  string value = 1;
}

NOTE: File level comments should be leading comments on the syntax directive.

Trailing comments

Fields, Service Methods, Enum Values and Extensions support trailing comments.

enum MyEnum {
  DEFAULT = 0; // the default value
  OTHER   = 1; // the other value
}

Excluding comments

If you want to have some comment in your proto files, but don't want them to be part of the docs, you can simply prefix the comment with @exclude.

Example: include only the comment for the id field

/**
 * @exclude
 * This comment won't be rendered
 */
message ExcludedMessage {
  string id   = 1; // the id of this message.
  string name = 2; // @exclude the name of this message

  /* @exclude the value of this message. */
  int32 value = 3;
}

Check out the example protos to see all the options.

Output Example

With the input .proto files

• Booking.proto
• Customer.proto
• Vehicle.proto

the plugin gives the output

• Markdown
• HTML
• DocBook
• JSON

Check out the examples task in the Makefile to see how these were generated.

Documentation

Overview

Package gendoc is a protoc plugin for generating documentation from your proto files.

Typically this will not be used as a library, though nothing prevents that. Normally it'll be invoked by passing `--doc_out` and `--doc_opt` values to protoc.

Example: generate HTML documentation

protoc --doc_out=. --doc_opt=html,index.html protos/*.proto

Example: exclude patterns

protoc --doc_out=. --doc_opt=html,index.html:google/*,somedir/* protos/*.proto

Example: use a custom template

protoc --doc_out=. --doc_opt=custom.tmpl,docs.txt protos/*.proto

For more details, check out the README at https://github.com/pseudomuto/protoc-gen-doc

Index

• Constants
• func NoBrFilter(content string) string
• func PFilter(content string) template.HTML
• func ParaFilter(content string) string
• func RenderTemplate(kind RenderType, template *Template, inputTemplate string) ([]byte, error)
• type Enum
• type EnumValue
• type File
• type FileExtension
• type Message
• type MessageExtension
• type MessageField
• type Plugin
  • func (p *Plugin) Generate(r *plugin_go.CodeGeneratorRequest) (*plugin_go.CodeGeneratorResponse, error)
• type PluginOptions
  • func ParseOptions(req *plugin_go.CodeGeneratorRequest) (*PluginOptions, error)
• type Processor
• type RenderType
  • func NewRenderType(renderType string) (RenderType, error)
• type ScalarValue
• type Service
• type ServiceMethod
• type Template
  • func NewTemplate(descs []*protokit.FileDescriptor) *Template

Constants

const VERSION = "1.1.0"

VERSION is the version of protoc-gen-doc being used.

Functions

func NoBrFilter

func NoBrFilter(content string) string

NoBrFilter removes single CR and LF from content.

func PFilter

func PFilter(content string) template.HTML

PFilter splits the content by new lines and wraps each one in a <p> tag.

func ParaFilter

func ParaFilter(content string) string

ParaFilter splits the content by new lines and wraps each one in a <para> tag.

func RenderTemplate

func RenderTemplate(kind RenderType, template *Template, inputTemplate string) ([]byte, error)

RenderTemplate renders the template based on the render type. It supports overriding the default input templates by supplying a non-empty string as the last parameter.

Example: generating an HTML template (assuming you've got a Template object)

data, err := RenderTemplate(RenderTypeHTML, &template, "")

Example: generating a custom template (assuming you've got a Template object)

data, err := RenderTemplate(RenderTypeHTML, &template, "{{range .Files}}{{.Name}}{{end}}")

Types

type Enum

type Enum struct {
	Name        string       `json:"name"`
	LongName    string       `json:"longName"`
	FullName    string       `json:"fullName"`
	Description string       `json:"description"`
	Values      []*EnumValue `json:"values"`
}

Enum contains details about enumerations. These can be either top level enums, or nested (defined within a message).

type EnumValue

type EnumValue struct {
	Name        string `json:"name"`
	Number      string `json:"number"`
	Description string `json:"description"`
}

EnumValue contains details about an individual value within an enumeration.

type File

type File struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Package     string `json:"package"`

	HasEnums      bool `json:"hasEnums"`
	HasExtensions bool `json:"hasExtensions"`
	HasMessages   bool `json:"hasMessages"`
	HasServices   bool `json:"hasServices"`

	Enums      orderedEnums      `json:"enums"`
	Extensions orderedExtensions `json:"extensions"`
	Messages   orderedMessages   `json:"messages"`
	Services   orderedServices   `json:"services"`
}

File wraps all the relevant parsed info about a proto file. File objects guarantee that their top-level enums, extensions, messages, and services are sorted alphabetically based on their "long name". Other values (enum values, fields, service methods) will be in the order that they're defined within their respective proto files.

In the case of proto3 files, HasExtensions will always be false, and Extensions will be empty.

type FileExtension

type FileExtension struct {
	Name               string `json:"name"`
	LongName           string `json:"longName"`
	FullName           string `json:"fullName"`
	Description        string `json:"description"`
	Label              string `json:"label"`
	Type               string `json:"type"`
	LongType           string `json:"longType"`
	FullType           string `json:"fullType"`
	Number             int    `json:"number"`
	DefaultValue       string `json:"defaultValue"`
	ContainingType     string `json:"containingType"`
	ContainingLongType string `json:"containingLongType"`
	ContainingFullType string `json:"containingFullType"`
}

FileExtension contains details about top-level extensions within a proto(2) file.

type Message

type Message struct {
	Name        string `json:"name"`
	LongName    string `json:"longName"`
	FullName    string `json:"fullName"`
	Description string `json:"description"`

	HasExtensions bool `json:"hasExtensions"`
	HasFields     bool `json:"hasFields"`

	Extensions []*MessageExtension `json:"extensions"`
	Fields     []*MessageField     `json:"fields"`
}

Message contains details about a protobuf message.

In the case of proto3 files, HasExtensions will always be false, and Extensions will be empty.

type MessageExtension

type MessageExtension struct {
	FileExtension

	ScopeType     string `json:"scopeType"`
	ScopeLongType string `json:"scopeLongType"`
	ScopeFullType string `json:"scopeFullType"`
}

MessageExtension contains details about message-scoped extensions in proto(2) files.

type MessageField

type MessageField struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	Label        string `json:"label"`
	Type         string `json:"type"`
	LongType     string `json:"longType"`
	FullType     string `json:"fullType"`
	DefaultValue string `json:"defaultValue"`
}

MessageField contains details about an individual field within a message.

In the case of proto3 files, DefaultValue will always be empty. Similarly, label will be empty unless the field is repeated (in which case it'll be "repeated").

type Plugin

type Plugin struct{}

Plugin describes a protoc code generate plugin. It's an implementation of Plugin from github.com/pseudomuto/protokit

func (*Plugin) Generate

func (p *Plugin) Generate(r *plugin_go.CodeGeneratorRequest) (*plugin_go.CodeGeneratorResponse, error)

Generate compiles the documentation and generates the CodeGeneratorResponse to send back to protoc. It does this by rendering a template based on the options parsed from the CodeGeneratorRequest.

type PluginOptions

type PluginOptions struct {
	Type            RenderType
	TemplateFile    string
	OutputFile      string
	ExcludePatterns []*regexp.Regexp
}

PluginOptions encapsulates options for the plugin. The type of renderer, template file, and the name of the output file are included.

func ParseOptions

func ParseOptions(req *plugin_go.CodeGeneratorRequest) (*PluginOptions, error)

ParseOptions parses plugin options from a CodeGeneratorRequest. It does this by splitting the `Parameter` field from the request object and parsing out the type of renderer to use and the name of the file to be generated.

The parameter (`--doc_opt`) must be of the format <TYPE|TEMPLATE_FILE>,<OUTPUT_FILE>:<EXCLUDE_PATTERN>,<EXCLUDE_PATTERN>*. The file will be written to the directory specified with the `--doc_out` argument to protoc.

type Processor

type Processor interface {
	Apply(template *Template) ([]byte, error)
}

Processor is an interface that is satisfied by all built-in processors (text, html, and json).

type RenderType

type RenderType int8

RenderType is an "enum" for which type of renderer to use.

const (
	RenderTypeDocBook RenderType
	RenderTypeHTML
	RenderTypeJSON
	RenderTypeMarkdown
)

Available render types.

func NewRenderType

func NewRenderType(renderType string) (RenderType, error)

NewRenderType creates a RenderType from the supplied string. If the type is not known, (0, error) is returned. It is assumed (by the plugin) that invalid render type simply means that the path to a custom template was supplied.

type ScalarValue

type ScalarValue struct {
	ProtoType  string `json:"protoType"`
	Notes      string `json:"notes"`
	CppType    string `json:"cppType"`
	CSharp     string `json:"csType"`
	GoType     string `json:"goType"`
	JavaType   string `json:"javaType"`
	PhpType    string `json:"phpType"`
	PythonType string `json:"pythonType"`
	RubyType   string `json:"rubyType"`
}

ScalarValue contains information about scalar value types in protobuf. The common use case for this type is to know which language specific type maps to the protobuf type.

For example, the protobuf type `int64` maps to `long` in C#, and `Bignum` in Ruby. For the full list, take a look at https://developers.google.com/protocol-buffers/docs/proto3#scalar

type Service

type Service struct {
	Name        string           `json:"name"`
	LongName    string           `json:"longName"`
	FullName    string           `json:"fullName"`
	Description string           `json:"description"`
	Methods     []*ServiceMethod `json:"methods"`
}

Service contains details about a service definition within a proto file.

type ServiceMethod

type ServiceMethod struct {
	Name             string `json:"name"`
	Description      string `json:"description"`
	RequestType      string `json:"requestType"`
	RequestLongType  string `json:"requestLongType"`
	RequestFullType  string `json:"requestFullType"`
	ResponseType     string `json:"responseType"`
	ResponseLongType string `json:"responseLongType"`
	ResponseFullType string `json:"responseFullType"`
}

ServiceMethod contains details about an individual method within a service.

type Template

type Template struct {
	// The files that were parsed
	Files []*File `json:"files"`
	// Details about the scalar values and their respective types in supported languages.
	Scalars []*ScalarValue `json:"scalarValueTypes"`
}

Template is a type for encapsulating all the parsed files, messages, fields, enums, services, extensions, etc. into an object that will be supplied to a go template.

func NewTemplate

func NewTemplate(descs []*protokit.FileDescriptor) *Template

NewTemplate creates a Template object from a set of descriptors.