sabledocs
markvincze.github.io
- Free plan
- Windows
- macOS
- Linux
What sabledocs is
sabledocs is a free, open-source generator for static documentation about Protobuf and gRPC contracts. It runs from a command line and can produce one HTML documentation site for multiple packages, covering both contract types. The input is a binary Protobuf descriptor made with protoc; comments require the descriptor to include source information. Search is enabled by default and can use a prebuilt Lunr index, while Markdown works in the main content page and in Protobuf comments. Configuration in sabledocs.toml can control titles, input and output paths, package visibility, member ordering, and comment filtering. Jinja templates can be customized for primary content, and additional templates can be added to the generated site. Configuration can also add source links for Protobuf model members in GitHub, Bitbucket, Bitbucket Data Center, and GitLab repositories. Output is placed in sabledocs_output and can be opened through index.html. The package requires Python 3.11 or higher and is installed with pip install sabledocs. A Docker image is available with protoc and sabledocs preinstalled. The documented workflow suits reference publishing, including CI builds.
Who it suits
sabledocs suits people generating and publishing reference documentation for Protobuf and gRPC contracts, including through CI builds. It may fit teams that want configurable static HTML output and source links to supported repository types.
Good to know, and what to watch
- Generates one site for multiple packages.
- Supports both Protobuf and gRPC contracts.
- Search is enabled by default.
- Jinja templates and output options can be customized.
- Requires Python 3.11 or higher.
- Build input must be a binary descriptor generated with protoc.
- Comments require the descriptor to include source information.
Plans
Every plan and priceSabledocs
Free plan
Getting started
- Install Python 3.11 or newer
- Install the package with pip install sabledocs
- Generate a binary Protobuf descriptor with protoc
- Include --include_source_info when comments are required
- Configure titles, paths, visibility, ordering, and filters in sabledocs.toml
- Run the command-line build and open index.html from sabledocs_output
Limits to check
The package requires Python 3.11 or newer, and documentation generation depends on a binary descriptor created by protoc. Protobuf comments require the descriptor's `--include_source_info` data.
The Club's review
sabledocs is a command-line generator for static reference documentation built from Protobuf and gRPC contracts. It is best for teams that control their contract build and want to publish the resulting docs through their own workflow. Its main appeal is focused, configurable output at no cost; its main constraint is the required Python and descriptor setup.
Overview
The generator turns a binary Protobuf descriptor into a static HTML site in sabledocs_output, which can be opened from index.html. That output is a good fit for publishing reference material alongside a codebase or through an existing deployment process. It is documentation infrastructure, not a client for calling or testing gRPC services.
Installation uses pip install sabledocs and requires Python 3.11 or higher. Builds also depend on a descriptor generated with protoc. Protobuf comments are included only when the descriptor is built with --include_source_info, so teams must preserve that option if comments are part of their reference content.
Key features
sabledocs can combine Protobuf and gRPC contracts from multiple packages in one site, which is useful when readers need a unified reference rather than separate pages for each package. Search is enabled by default and uses a prebuilt Lunr index, keeping navigation within the static output.
Markdown works in the main content page and in Protobuf comments. The sabledocs.toml configuration covers titles, input and output paths, package visibility, member ordering, comment filtering, and other generation options. This gives maintainers control over how the reference is presented without changing the contracts themselves.
Source links can be added for Protobuf model members, with support for GitHub, Bitbucket, Bitbucket Data Center, and GitLab repositories. Jinja templates can be customized for primary content, and extra templates can be added to the generated output. These options make the generator more adaptable to an existing documentation style, though they add configuration work compared with accepting default output.
An advanced option preprocesses comments with a custom Python parser. That can support specialized comment handling, but the maker cautions that it may make whitespace-sensitive formatting harder. A Docker image with both protoc and sabledocs preinstalled is available, which can simplify builds that otherwise need to coordinate those dependencies.
Pricing
sabledocs is free and open source. The Sabledocs plan is free and provides an open-source static generator; it requires Python 3.11 or higher and a Protobuf descriptor file. There is no paid tier to unlock the documented generation features, so the trade-off is managing the build and deployment yourself rather than using a hosted documentation service.
Platforms
The documented platforms are Linux, macOS, and Windows. The deployment model is self-hosted, so teams choose where and how to publish the generated site.
Who it's for
This is a sensible choice for developers and platform teams who already generate Protobuf descriptors and need reference docs for multiple packages or gRPC contracts. CI workflows are a natural fit because the generator produces static files from a defined build input. It is less suitable for readers seeking an interactive API client, or for teams that do not control descriptor generation and cannot ensure comments are retained.
Pros and cons
- Multi-package output: one site can bring Protobuf and gRPC contracts together, reducing fragmentation for readers.
- Flexible presentation: configuration, Markdown, source links, and Jinja templates allow teams to shape the generated reference.
- No license cost: the open-source generator is free to use, with no paid plan required for its documented capabilities.
- Build prerequisites: Python 3.11 or higher and a binary descriptor generated with protoc are required.
- Comments need an explicit build option: without --include_source_info, comment-based documentation will not appear.
- Static documentation only: it does not replace a tool for sending requests to or testing gRPC services.
Alternatives
For a wider look at tools in this category, browse gRPC Tools.
Choose protoc-gen-doc if you want a free, MIT-licensed option for generating Protobuf documentation instead; it supports Linux, macOS, and Windows as well as self-hosted use. Choose Kreya instead if you need a gRPC client: its free plan is for individuals and limits request history to the latest request, and it is not open source.
FintX is another free, open-source option for gRPC client work, with unlimited gRPC clients, request auto-save, import and export, tabs per method, a JSON editor, and projects. For load testing, ghz is a free open-source gRPC load-testing CLI and Go package; its complementary web application is in beta.
grpcmd is a free alternative for sending requests, starting a server, reflection, listing and describing methods, and JavaScript scripting. The gRPC CLI offers a free build-from-source option for unary RPC calls, while grpcmock-go provides free open-source gRPC testing utilities for Go. ProtoCall is a freemium app whose free plan supports GitHub imports and manually created workspaces.
Verdict
Choose sabledocs if you need free, configurable static reference sites for Protobuf and gRPC contracts and can manage the descriptor-based build yourself. Its strongest reason to choose it is the combination of multi-package output and control over content and templates without a license cost. Look elsewhere if the job is making or testing gRPC calls, or if your workflow cannot supply the required descriptor and Python runtime.
The verdict
sabledocs offers configurable static reference sites for Protobuf and gRPC contracts, with search, Markdown, and template support. The workflow depends on Python 3.11+ and a correctly generated descriptor file.
Questions people ask
What does Sabledocs generate?
It creates a static HTML documentation site for Protobuf and gRPC contracts. The output is placed in `sabledocs_output` and can be opened through `index.html`.
Is Sabledocs free and open source?
Yes. The listed plan is free at no cost, and the maker describes the project as open source.
Which systems can run Sabledocs?
It is listed for Linux, macOS, and Windows. A Docker image is also available with protoc and Sabledocs preinstalled.
What input does the build use?
The generator consumes a binary Protobuf descriptor made with protoc. Comments are included when the descriptor is generated with `--include_source_info`.
Can the generated site be customized?
Yes. `sabledocs.toml` controls settings such as titles, paths, visibility, ordering, and comment filtering. Jinja templates can customize primary content and add extra generated files.
What the maker publishes
- Audience
- The documented workflow is for people generating and publishing reference documentation for Protobuf and gRPC contracts, including in CI builds. source
- Comment parsing
- An advanced option lets users preprocess Protobuf comments with a custom Python parser; the page cautions that this may make whitespace-sensitive formatting harder. source
- Contract support
- It can combine Protobuf and gRPC contracts in generated documentation. source
- Customization
- Users can configure titles, input and output paths, package visibility, member ordering, comment filtering, and other generation options in sabledocs.toml. source
- Custom templates
- Users can configure Jinja templates for primary content and add extra templates to generated output. source
- Distribution
- The documentation instructs users to install the package with pip install sabledocs. source
- Docker
- A Docker image is available with both protoc and Sabledocs preinstalled. source
- Docker
- A Docker image is available for CI and other workflows, with protoc and Sabledocs preinstalled. source
- Free and open source
- The demo page describes Sabledocs as free and open source. source
- Generation
- Sabledocs uses a command-line interface to generate static HTML documentation. source
- Input
- It builds documentation from a binary Protobuf descriptor generated with protoc, and comments require the --include_source_info flag to be included. source
- License and project status
- The maker’s site describes the project as open source. source
- Markdown
- Markdown is supported in the main content page and in Protobuf comments. source
- Markdown
- Markdown is supported in the main content page and Protobuf comments, including fenced and indented code blocks. source
- Multiple packages
- It can build one documentation site for multiple packages. source
- Output
- The generator creates a documentation site in sabledocs_output that can be opened through index.html. source
- Prerequisite
- The package requires Python 3.11 or higher, and the build process uses a binary descriptor generated with protoc. source
- Purpose
- Sabledocs is a static documentation generator for Protobuf and gRPC contracts. source
- Purpose
- Sabledocs is a static documentation generator for Protobuf and gRPC contracts. source
- Runtime requirement
- The package requires Python version 3.11 or higher. source
- Search
- Search can be enabled with a prebuilt Lunr index and is enabled by default. source
- Search
- A prebuilt Lunr search index can be enabled or disabled through configuration and defaults to enabled. source
- Security
- The maker’s site does not state security certifications or compliance claims. source
- Source links
- Configuration can add source code links for Protobuf model members, with GitHub, Bitbucket, Bitbucket Data Center, and GitLab repository types supported. source
Checked against the maker's pages on 7 Oct 2026.