Usage

`docusaurus-protobuffet`#

This toolset provides a suite of CLI commands to generate and manage documentation files for your Protobuf workspace. These generated files follow the Docusaurus convention of using MDX files and React components.

CLI Commands#

generate-proto-docs#

npx docusaurus generate-proto-docs

Generate documentation for all Protobuf files within the configured fileDescriptorsPath JSON file. The generated files are written to protoDocsPath. A sidebar object is written to the configured sidebarPath. View the configuration section for details of these options.

This command must be run for every content change of fileDescriptorsPath. This will overwrite all previously generated files, so they should not be modified manually. Extension support for these generated files will be coming in the future, so please reach out with your use cases.

You can view some generated doc files in the landing page.

Generating the `fileDescriptorsPath` File#

This project depends on a snapshot of all the files within your Protobuf workspace. The formatting and generation of this snapshot currently depends on the protoc-gen-doc Protobuf compiler plugin. protoc-gen-doc can generate a JSON representation of your Protobuf files, which we parse to build an enhanced view of your documentation.

To use protoc-gen-doc we must install golang and protoc. These are already common dependencies when working with Protobuf files, but I'm happy to investigate alternatives if we decide this is a barrier for users.

# install protoc. change for your OS as necessary.
brew install protobuf

# install protoc-gen-doc. this depends on golang.
go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc

# use protoc to generate the JSON representation of your Protobuf workspace.
protoc --doc_out=./fixtures --doc_opt=json,proto_workspace.json protos/**/*.proto

Configuration#

// file: docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      'docusaurus-protobuffet',
      {
        protobuffet: {
          fileDescriptorsPath: './fixtures/proto_workspace.json',
          protoDocsPath: './protodocs',
          sidebarPath: './sidebarsProtodocs.js'
        }
      }
    ]
  ],
  // ...
}

`protobuffet`#

Pass in all plugin options. See docusaurus-protobuffet-plugin for the plugin library. This preset assigns some recommended defaults for missing options.

Option	Description	Required	Default
`fileDescriptorsPath`	Path to JSON file containing generated proto documentation through protoc-gen-doc. See usage section for details.	✅	`./fixtures/proto_workspace.json`
`protoDocsPath`	Directory where CLI will create doc files.		`./protodocs`
`sidebarPath`	Path to file where CLI will write the generated Sidebar object.		`./sidebarsProtodocs.js`

`docusaurus-protobuffet-init`#

For those without an existing Docusaurus project, this package can scaffold a new site with Protobuffet packages installed in a recommended setup.

Note: These commands should be run from your root directory where you would like the site to be created.

Run the generator. This will create a directory for your site with the generated files. You must specify the project_name variable.

npx docusaurus-protobuffet-init init <project_name>

Start the development server to view the sample fixtures. See the configuration section for steps on introducing your own Protobuf workspace file.

cd <project_name>
npm run start

Proto doc files were generated for the sample fixture during project initialization. These will need to be generated whenever the fileDescriptorsPath file (defaulted to ./fixtures/proto_workspace.json) is updated. Read docusaurus-protobuffet CLI documentation for details.

npx docusaurus generate-proto-docs

Since this is a normal Docusaurus project, you can follow their documentation for deployments and other details.

docusaurus-protobuffet#