Skip to main content

8 View Generated Documentation

You can browse autogenerated documentation for your module in the BSR.

Simply navigate to the /docs page in your browser for the module you just created. For example, if your $BUF_USER is set to acme and you created the buf.build/acme/petapis module, you can visit the https://buf.build/acme/petapis/docs page (i.e. replace acme with your $BUF_USER in this link).

8.1 Add a buf.md#

The page you see above serves as the primary entrypoint for your module's documentation. But as you can see from the default buf.md content, we currently don't have any module-level documentation.

You can update the module-level documentation page by creating a buf.md in the same directory as your module's buf.yaml, and pushing it up to the BSR. In this way, the buf.md file is analogous to a GitHub repository's README.md. The buf.md file currently supports all of the CommonMark syntax.

Let's start by adding a simple note like so:

$ touch buf.md
buf.md
## PetAPIs
This module contains all of the APIs required to interact with the `PetStoreService`.

For clarity, your petapis directory should now look like the following:

petapis/├── buf.md├── buf.yaml├── google│   └── type│       └── datetime.proto└── pet    └── v1        └── pet.proto

Now if you push your module again, you'll notice a new commit and the documentation will be updated to reflect the latest changes:

$ buf push4514ddced0584e73a100e82096c7958c

If you refresh the documentation page, you should see the changes you just introduced with the buf.md.

8.2 Package Documentation#

As you can see from the module documentation page, both the pet.v1 and google.type packages are available as links. Click on the pet.v1 link to navigate to its package documentation (i.e. https://buf.build/acme/petapis/docs/main/pet.v1).

From here, you can click through each of the Protobuf type definitions, and see all of the comments associated with each type. In fact, if you click on the google.type.DateTime message referenced in the Pet message, you'll be brought to the google.type.v1 package documentation for the same commit.

For an example of API documentation, check out googleapis.