Skip to main content

Generated 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. Navigate to a repository within the BSR and click the Docs tab.

BSR module

For an example see the demolab/theweather module by visiting https://buf.build/demolab/theweather/docs.

Module documentation#

The majority of documentation will come directly from comments associated with your Protobuf definitions. But, there also needs to be a simple 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 will result in new commits in the BSR.

The buf.md file is analogous to a GitHub repository's README.md and currently supports all of the CommonMark syntax.

BSR module

Package documentation#

The package level documentation provides Protobuf type definitions and comments for all package files. Clicking through the type definitions will take 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 will have a unique placeholder within the page, an anchor tag, making it easy to share links referencing the exact item.

BSR module