Skip to content

Custom Templates

Jump to bottom Edit New page
Tim Möhlmann edited this page Oct 7, 2021 · 56 revisions

The tool supports fully custom output formats through user-provided Mustache templates.

Basic Example

Generating documentation from

Person.proto Pet.proto 
/// Describes a person.
message Person {
  /// Name of person.
  required string name = 1;
/// Age of person.
required int32 age = 2;
}
 
import "Person.proto";

/// Describes a pet.
message Pet {
    /// Type of animal.
    required string animal = 1;

    /// Owner of the pet.
    optional Person owner = 2;
}
</td>

using the custom Mustache template

example.mustache
{{#files}}
File: {{file_name}}
{{#file_messages}}
  Message: {{message_name}}
  Description: {{message_description}}
  Fields:
  {{#message_fields}}
    {{field_name}}
      {{field_description}}
  {{/message_fields}}
{{/file_messages}}
{{/files}}

by running

protoc --doc_out=example.mustache,example.txt:. Person.proto Pet.proto

will produce

example.txt
File: Person.proto
  Message: Person
  Description: Describes a person.
  Fields:
    name
      Name of person.
    age
      Age of person.
File: Pet.proto
  Message: Pet
  Description: Describes a pet.
  Fields:
    animal
      Type of animal.
    owner
      Owner of the pet.

in the current working directory.

See examples/templates for some user-contributed example templates, or have a look at the built-in templates in resources for even bigger examples.

Template Input Data Format

The custom Mustache template is instantiated with data having the following structure:

  • files: Array of objects, each with the structure:
    • file_name: Name of processed file.
    • file_description: Description of processed file. 1
    • file_package: Package of processed file, or an empty string.
    • file_messages: Array of objects, each with the structure:
      • message_name: Name of message.
      • message_full_name: Full name of message. 2
      • message_long_name: Long name of message. 2
      • message_description: Description of message. 1
      • message_fields: Array of objects, each with the structure:
        • field_name: Name of field.
        • field_description: Description of field. 1
        • field_label: Field label ("required", "optional" or "repeated").
        • field_type: Name of field type.
        • field_full_type: Full name of field type. 2
        • field_long_type: Long name of field type. 2
        • field_default_value: Default value of field, or an empty string. 3
      • message_has_fields: true if the message has 1 or more fields defined.
      • message_has_extensions: true if message has any nested extensions.
      • message_extensions: Array of objects, each with the structure:
        • extension_name: Name of extension.
        • extension_full_name: Full name of extension. 2
        • extension_long_name: Long name of extension. 2
        • extension_description: Description of extension. 1
        • extension_label: Extension label ("optional" or "repeated").
        • extension_type: Name of extension type.
        • extension_full_type: Full name of extension type. 2
        • extension_long_type: Long name of extension type. 2
        • extension_number: Extension number.
        • extension_default_value: Default value of extension, or an empty string. 3
        • extension_containing_type: Name of extended type.
        • extension_containing_full_type: Full name of extended type. 2
        • extension_containing_long_type: Long name of extended type. 2
        • extension_scope_type: Name of extension scope type.
        • extension_scope_full_type: Full name of extension scope type. 2
        • extension_scope_long_type: Long name of extension scope type. 2
    • file_enums: Array of objects, each with the structure:
      • enum_name: Name of enumeration.
      • enum_full_name: Full name of enumeration. 2
      • enum_long_name: Long name of enumeration. 2
      • enum_description: Description of enumeration. 1
      • enum_values: Array of objects, each with the structure:
        • value_name: Name of enumeration value.
        • value_number: Number of enumeration value.
        • value_description: Description of enumeration value. 1
    • file_has_extensions: true if any extensions are defined at file scope.
    • file_extensions: Same as message_extensions, but no extension_scope_* fields.
    • file_has_services: true if any services are defined in the file.
    • file_services: Array of objects, each with the structure:
      • service_name: Name of service.
      • service_full_name: Full name of service. 2
      • service_long_name: Long name of service. 2
      • service_description: Description of service. 1
      • service_methods: Array of objects, each with the structure:
        • method_name: Name of method.
        • method_description: Description of method. 1
        • method_request_type: Name of method input type.
        • method_request_full_type: Full name of method input type. 2
        • method_request_long_type: Long name of method input type. 2
        • method_response_type: Name of method output type.
        • method_response_full_type: Full name of method output type. 2
        • method_response_long_type: Long name of method output type. 2
  • scalar_value_types: Array of objects, each with the structure: 4
    • scalar_value_proto_type: Google Protocol Buffers type name (e.g. "sfixed64").
    • scalar_value_cpp_type: C++ type name (e.g. "int64").
    • scalar_value_cs_type: C# type name (e.g. "long").
    • scalar_value_go_type: Go type name (e.g. "int64").
    • scalar_value_java_type: Java type name (e.g. "long").
    • scalar_value_php_type: PHP type name (e.g. "integer/string").
    • scalar_value_python_type: Python type name (e.g. "int/long").
    • scalar_value_ruby_type: Ruby type name (e.g. "Bignum").
    • scalar_value_notes: Notes about this scalar value type.

1 Taken from the corresponding documentation comment. If the item is undocumented, the description is an empty string.

2 *_full_* fields hold the dot separated full name, e.g. "baz.Bar.Foo" if Foo is nested in Bar in package baz. *_long_* fields hold the same, but with the package part omitted. If a type is scalar, the name, full name and long name are always the same (e.g. "int32").

3 If of type string, the *_default_value field includes surrounding double quotes. If of type bytes, the default value is 0x followed by a hex representation of the value. Only non-empty if a default value was explicitly specified in the .proto file.

4 The scalar_value_types array is always the same and included for the convenience of template authors who may wish to present the available scalar value types as part of their documentation. Its content is taken from the table in the Google Protocol Buffers documentation.

Array Order Guarantees

The file_messages, file_enums, file_extensions and file_services arrays are ordered alphabetically by message_long_name, enum_long_name, extension_long_name and service_long_name, respectively, while message_fields, message_extensions, enum_values and service_methods are in the same order as in the .proto file. No guarantee is given about the order of elements in other arrays.

Available Mustache Lambdas

The tool also provides a couple of Mustache lambdas that can be useful if you're generating Markdown, HTML or DocBook:

Lambda Description
{{#nobr}}...{{/nobr}} Strips LF and CRLF sequences.
{{#p}}...{{/p}} Wraps blank-line separated paragraphs in <p>...</p>.
{{#para}}...{{/para}} Wraps blank-line separated paragraphs in <para>...</para>.
Add a custom footer
Add a custom sidebar
Clone this wiki locally