Generated API documentation

The BSR comes with complete documentation for your Protobuf files through a browsable UI with syntax highlighting, one click navigation between definitions and references. Every push to the BSR generates documentation. You may browse the documentation section of a repository by navigating to the Docs tab.

For an example see the connectrpc/eliza module by visiting https://buf.build/connectrpc/eliza.

Module documentation

Most documentation comes directly from comments associated with your Protobuf definitions. But there also needs to be a way for authors to describe their module for others to understand its functionality.

To accomplish this, you add a buf.md file to the same directory as your module's buf.yaml file and push it to the BSR like normal. Since documentation is part of your module, any updates to your buf.md result in new commits in the BSR.

The buf.md file is analogous to a GitHub repository's README.md.

Package documentation

The package level documentation provides Protobuf type definitions and comments for all package files. Clicking through the type definitions takes you to the referenced item.

You can quickly navigate from the docs to the Protobuf file by clicking the filename on the right-hand side.

Each type definition has a unique placeholder within the page, an anchor tag, enabling you to share links to the exact item.

Package description

When sharing packages it is often useful to provide an overview of the package. You can do so by adding comments above the package directive in your .proto file.

Comments on the package directive are not merged across files. Files are parsed alphabetically, and only the first file with a non-empty comment is displayed in the generated documentation.

Supported formatting syntax

The module documentation and package documentation, including Protobuf type definitions and comments, support the following syntax for formatting.

• CommonMark - standardized common features of Markdown.
• Github Flavored Markdown - Markdown extension developed by GitHub, including additional features like task lists and tables.
• Mermaid - tool for diagramming and charting.

Annotated Protobuf options

The generated documentation renders annotated Protobuf options. You can find the complete list of Protobuf's built-in options available in the descriptor.proto.

List of options rendered in the generated documentation

Message Options

• deprecated

Field options

• deprecated
• packed
• ctype
• jstype
• lazy
• unverified_lazy
• weak
• uninterpreted_option

Enum options

• allow_alias
• deprecated
• uninterpreted_option

EnumValue options

• deprecated
• uninterpreted_option

Service options

• deprecated
• uninterpreted_option

Method options

• deprecated
• idempotency_level
• uninterpreted_option

Custom options

Custom options are also supported and rendered in the generated documentation as well. You can find out how to create and apply a Custom option in your .proto file through the official protobuf docs.

syntax = "proto3";

package main.options.v1;

extend google.protobuf.EnumValueOptions {
  string country_code_abbrv = 2000;
}

extend google.protobuf.MessageOptions {
  optional int32 my_custom_option = 20003;
}

enum CountryCode {
  COUNTRY_CODE_UNSPECIFIED = 0;
  COUNTRY_CODE_INDIA = 1 [(country_code_abbrv) = "IND"];
  COUNTRY_CODE_UNITED_KINGDOM = 2 [(country_code_abbrv) = "GBR"];
  COUNTRY_CODE_UNITED_STATE_OF_AMERICA = 3 [(country_code_abbrv) = "USA"];
}

message SampleMessage {
  option (my_custom_option) = 10000;
}