Skip to content

SDK documentation#

Generated SDKs are largely self-documenting. They include complete instructions for installing via the relevant package manager, or downloading an archive if that's not available. Some SDKs also provide a generated API reference.

In addition, you can add a "Getting started" guide to your SDKs to provide additional context to users.

Getting started guide#

Each SDK provides an open-text Markdown editor for the guide, allowing you to customize the content for the associated plugin.

You must be a BSR instance admin or have the Owner or Admin role in the module's parent organization to access the editor.

Add a guide#

  1. Go to the SDKs tab of the module: https://buf.build/OWNER/MODULE/sdks.
  2. Choose the plugin you want to create a guide for.
  3. Click Open the Markdown editor.
  4. Begin writing or paste in your text from another source.
  5. When you're done editing the text, click Publish. The guide is immediately visible to anyone who goes to that SDK.

You can format the text and add images or tables using Markdown or use the WYSIWYG buttons. Image URLs must be publicly addressable—the editor doesn't allow you to upload images.

Edit or delete a guide#

You can edit the guide anytime by clicking Edit. Make your changes and click Publish to publish the revision.

To delete the guide, click the trash can icon at the top right of the editor.

Warning

SDK getting started guides aren't version-controlled resources. When their content is changed or deleted, older versions can't be recovered.

API reference#

Most Go and JavaScript/Typescript SDKs have an easily accessible API reference on the SDK page. It's always in sync with the plugin version and module commit specified by the SDK, and is presented in the way that's standard for each language. Click the API reference button at the top right of the SDK to view it.

Screenshot of the API reference button

If the API reference for the SDK hasn't been generated before, the BSR displays a "Docs Generating" banner—otherwise, it displays a link to the reference's root directory. Click through to a package and it shows its import statement and links to each of the package's descendants—you can navigate around the documentation from there.