sabledocs 0.8.322.dev0

Static documentation generator for Protobuf and gRPC

Sabledocs

A simple static documentation generator for Protobuf and gRPC contracts.

Demo: You can check out this demo showing the generated documentation for some of the Google Cloud SDK contracts.

How to use

Generate the proto descriptor

In order to build the documentation, you need to generate a binary descriptor from your Proto contracts using protoc. If you don't have it yet, the protoc CLI can be installed by downloading the release from the official protobuf repository.

For example in the folder where your proto files are located, you can execute the following command.

protoc *.proto -o descriptor.pb --include_source_info

(It's important to use the --include_source_info flag, otherwise the comments will not be included in the generated documentation.)

The generated descriptor.pb file will be the input needed to build the documentation site.

Build the documentation

Install the sabledocs package. It requires Python (version 3.11 or higher) to be installed.

pip install sabledocs

In the same folder where the generated descriptor.pb file is located, execute the command.

sabledocs

The documentation will be generated into a folder sabledocs_output, its main page can be opened with index.html.

Customization

For further customization, create a sabledocs.toml file in the folder where the Protobuf descriptor file is located and from which the sabledocs CLI is executed. You can customize the following options. Any omitted field will use its default value.

# Configures the main title of the documentation site.
# Default value: "Protobuf module documentation"
module-title = "My Awesome Module"

# Specifies the name of the Protobuf descriptor file.
# Default value: "descriptor.pb"
input-descriptor-file = "myawesomemodule.pb"

# Specifies the file which contains the content to display on the main page above the package list.
# Default value: ""
main-page-content-file = "intro.md"

# The output folder to which the documentation is generated.
# Default value: "sabledocs_output"
output-dir = "docs"

# Controls whether the the search functionality is enabled with a prebuilt Lunr index.
# Default value: true
enable-lunr-search = true

# Copyright message displayed in the footer.
# Default value: ""
footer-content = "© 2023 Jane Doe. All rights reserved."

# The following 3 fields configure the source control repository of the project.
# It is used to generate deeplink for the components of the Proto model pointing to the original source code.
# By default these fields are not configured, and source code links are not included in the docs.
# The repository-type field supports two possible values, "github" and "bitbucket".
# The fields repository-url and `repository-branch` should be configured to point to the correct repository.
repository-type = "github"
repository-url = "https://github.com/janedoe/myawesomeproject"
repository-branch = "main"

# In each comment, ignore everything that comes after (until end of the comment) one of the keywords.
# Default value: []
ignore-comments-after = ["@exclude"]
# In each comment, ignore all lines that contain at least one keyword from the following list.
# Default value: []
ignore-comment-lines-containing = ["buf:lint"]

# In the templates, one can now use non_hidden_packages instead of packages where the following are hidden:
# Default value: []
hidden-packages = ["google.protobuf"]

Main page content

Custom introduction content can be specified in a separate file, which can be displayed above the packages list on the main page of the documentation.
Then the name of the file has to be specified in the main-page-content-file configuration setting.

main-page-content-file = "intro.md"

See the example on the main page of the demo site.

For maintainers

Build the Python package:

python -m build

Publish with twine:

python -m twine upload --repository testpypi dist/*

Install from the local folder:

pip install .