gendoc

package module
v1.5.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 31, 2023 License: MIT Imports: 19 Imported by: 0

README

Usage

docker pull ppcelery/protoc-gen-doc:latest

docker run --rm \
        -v $(pwd):/out \
        -v $(pwd)/protocol:/protos \
        ppcelery/protoc-gen-doc:latest --doc_opt=markdown,api.md --proto_path=/protos \
            coordinator/v1/api.proto \
            join/v1/api.proto \
            kms/v2alpha1/api.proto \
            pki/v1/api.proto \
            common/v1/pki.proto \
            common/v1/ra.proto

Bug fix

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/Laisky/protoc-gen-doc

Index

Constants

View Source 
const VERSION = "1.5.1"

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

Variables

View Source 
var SupportedFeatures = uint64(plugin_go.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)

SupportedFeatures describes a flag setting for supported features.

Functions

func AnchorFilter added in v1.5.2 

func AnchorFilter(str string) string

AnchorFilter replaces all special characters with URL friendly dashes

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"`

	Options map[string]interface{} `json:"options,omitempty"`
}

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

func (Enum) Option added in v1.3.0 

func (e Enum) Option(name string) interface{}

Option returns the named option.

func (Enum) ValueOptions added in v1.3.0 

func (e Enum) ValueOptions() []string

ValueOptions returns all options that are set on the values in this enum.

func (Enum) ValuesWithOption added in v1.3.0 

func (e Enum) ValuesWithOption(optionName string) []*EnumValue

ValuesWithOption returns all values that have the given option set. If no single value has the option set, this returns nil.

type EnumValue 

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

	Options map[string]interface{} `json:"options,omitempty"`
}

EnumValue contains details about an individual value within an enumeration.

func (EnumValue) Option added in v1.3.0 

func (v EnumValue) Option(name string) interface{}

Option returns the named option.

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"`

	Options map[string]interface{} `json:"options,omitempty"`
}

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.

func (File) Option added in v1.3.0 

func (f File) Option(name string) interface{}

Option returns the named option.

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"`
	HasOneofs     bool `json:"hasOneofs"`

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

	Options map[string]interface{} `json:"options,omitempty"`
}

Message contains details about a protobuf message.

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

func (Message) FieldOptions added in v1.3.0 

func (m Message) FieldOptions() []string

FieldOptions returns all options that are set on the fields in this message.

func (Message) FieldsWithOption added in v1.3.0 

func (m Message) FieldsWithOption(optionName string) []*MessageField

FieldsWithOption returns all fields that have the given option set. If no single value has the option set, this returns nil.

func (Message) Option added in v1.3.0 

func (m Message) Option(name string) interface{}

Option returns the named option.

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"`
	IsMap        bool   `json:"ismap"`
	IsOneof      bool   `json:"isoneof"`
	OneofDecl    string `json:"oneofdecl"`
	DefaultValue string `json:"defaultValue"`

	Options map[string]interface{} `json:"options,omitempty"`
}

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").

func (MessageField) Option added in v1.3.0 

func (f MessageField) Option(name string) interface{}

Option returns the named option.

type Plugin added in v1.1.0 

type Plugin struct{}

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

func (*Plugin) Generate added in v1.1.0 

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
	SourceRelative  bool
}

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>[,default|source_relative]:<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"`

	Options map[string]interface{} `json:"options,omitempty"`
}

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

func (Service) MethodOptions added in v1.3.0 

func (s Service) MethodOptions() []string

MethodOptions returns all options that are set on the methods in this service.

func (Service) MethodsWithOption added in v1.3.0 

func (s Service) MethodsWithOption(optionName string) []*ServiceMethod

MethodsWithOption returns all methods that have the given option set. If no single method has the option set, this returns nil.

func (Service) Option added in v1.3.0 

func (s Service) Option(name string) interface{}

Option returns the named option.

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"`
	RequestStreaming  bool   `json:"requestStreaming"`
	ResponseType      string `json:"responseType"`
	ResponseLongType  string `json:"responseLongType"`
	ResponseFullType  string `json:"responseFullType"`
	ResponseStreaming bool   `json:"responseStreaming"`

	Options map[string]interface{} `json:"options,omitempty"`
}

ServiceMethod contains details about an individual method within a service.

func (ServiceMethod) Option added in v1.3.0 

func (m ServiceMethod) Option(name string) interface{}

Option returns the named option.

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
protoc-gen-doc
protoc-gen-doc is used to generate documentation from comments in your proto files.
 protoc-gen-doc is used to generate documentation from comments in your proto files.
Package extensions implements a system for working with extended options.
 Package extensions implements a system for working with extended options.
envoyproxy_validate
google_api_http
lyft_validate
validator_field

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.