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
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
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
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
currently supports all of the CommonMark syntax.
Let's start by adding a simple note like so:
$ touch 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
As you can see from the module documentation page, both the
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
message referenced in the
Pet message, you'll be brought to the
documentation for the same commit.
For an example of API documentation, check out googleapis.