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.
For an example see the
demolab/theweather module by visiting https://buf.build/demolab/theweather/docs.
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.
buf.md file is analogous to a GitHub repository's
README.md and currently supports all of the
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.