{"id":14530099,"url":"https://github.com/markvincze/sabledocs","last_synced_at":"2026-01-06T03:05:34.733Z","repository":{"id":148224008,"uuid":"539184242","full_name":"markvincze/sabledocs","owner":"markvincze","description":"Simple static documentation generator for Protobuf and gRPC contracts.","archived":false,"fork":false,"pushed_at":"2024-12-07T15:05:17.000Z","size":1012,"stargazers_count":60,"open_issues_count":12,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-19T14:03:28.670Z","etag":null,"topics":["documentation","grpc","protobuf"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markvincze.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-20T20:41:34.000Z","updated_at":"2024-12-17T15:59:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"49deb391-6fe4-45f2-a30a-fa9a30536465","html_url":"https://github.com/markvincze/sabledocs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markvincze%2Fsabledocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markvincze%2Fsabledocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markvincze%2Fsabledocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markvincze%2Fsabledocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markvincze","download_url":"https://codeload.github.com/markvincze/sabledocs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231732275,"owners_count":18418178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","grpc","protobuf"],"created_at":"2024-09-05T00:01:04.807Z","updated_at":"2026-01-06T03:05:34.724Z","avatar_url":"https://github.com/markvincze.png","language":"CSS","funding_links":[],"categories":["Tools","Documentation Types"],"sub_categories":["Other","API Documentation"],"readme":"# [Sabledocs](https://markvincze.github.io/sabledocs/)\n\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/markvincze/sabledocs/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/markvincze/sabledocs/tree/main)\n[![PyPi](https://img.shields.io/pypi/v/sabledocs.svg)](https://pypi.org/project/sabledocs/)\n[![Python versions](https://img.shields.io/pypi/pyversions/sabledocs.svg)](https://pypi.org/project/sabledocs/)\n\nA simple static documentation generator for Protobuf and gRPC contracts.\n\n**Demo**: You can check out this [demo](https://markvincze.github.io/sabledocs/demo/) showing the generated documentation for some of the [Google Cloud SDK contracts](https://github.com/googleapis/googleapis/tree/master/google/pubsub/v1).\n\n## How to use\n\n### Generate the proto descriptor\n\nIn 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](https://github.com/protocolbuffers/protobuf/releases) repository.\n\nFor example in the folder where your proto files are located, you can execute the following command.\n\n```\nprotoc *.proto -o descriptor.pb --include_source_info\n```\n\n*(It's important to use the `--include_source_info` flag, otherwise the comments will not be included in the generated documentation.)*\n\nThe generated `descriptor.pb` file will be the input needed to build the documentation site.\n\n### Build the documentation\n\nInstall the `sabledocs` package. It requires [Python](https://www.python.org/downloads/) (version 3.11 or higher) to be installed.\n\n```\npip install sabledocs\n```\n\nIn the same folder where the generated `descriptor.pb` file is located, execute the command.\n\n```\nsabledocs\n```\n\nThe documentation will be generated into a folder `sabledocs_output`, its main page can be opened with `index.html`.\n\n### Customization\n\nFor 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.\nYou can customize the following options. Any omitted field will use its default value.\n\n```toml\n# Configures the main title of the documentation site.\n# Default value: \"Protobuf module documentation\"\nmodule-title = \"My Awesome Module\"\n\n# Specifies the name of the Protobuf descriptor file.\n# Default value: \"descriptor.pb\"\ninput-descriptor-file = \"myawesomemodule.pb\"\n\n# Specifies the file which contains the content to display on the main page above the package list.\n# Default value: \"\"\nmain-page-content-file = \"intro.md\"\n\n# The output folder to which the documentation is generated.\n# Default value: \"sabledocs_output\"\noutput-dir = \"docs\"\n\n# Controls whether the the search functionality is enabled with a prebuilt Lunr index.\n# Default value: true\nenable-lunr-search = true\n\n# Copyright message displayed in the footer.\n# Default value: \"\"\nfooter-content = \"© 2023 Jane Doe. All rights reserved.\"\n\n# The following 3 fields configure the source control repository of the project.\n# They are used to generate deeplinks for the members of the Proto model pointing to the original source\n# code. By default these fields are not configured, and source code links are not included in the docs.\n# The repository-type field supports the following possible values, \"github\", \"bitbucket\", \"bitbucket-data-center\" and \"gitlab\".\n# The fields repository-url and repository-branch should be configured to point to the correct repository.\n# repository-dir should be set only if the root of your Protobuf module is in a specific directory inside your repository.\nrepository-type = \"github\"\nrepository-url = \"https://github.com/janedoe/myawesomeproject\"\nrepository-branch = \"main\"\nrepository-dir = \"proto\"\n\n# In each comment, ignore everything that comes after (until end of the comment) one of the keywords.\n# Default value: []\nignore-comments-after = [\"@exclude\"]\n# In each comment, ignore all lines that contain at least one keyword from the following list.\n# Default value: []\nignore-comment-lines-containing = [\"buf:lint\"]\n\n# Packages can be hidden from the generated documentation by adding them to the hidden-packages\n# collection. In the templates, the field non_hidden_packages can be used to access the packages which are\n# not listed in hidden-packages. (And the packages field returns all packages.)\n# Default value: []\nhidden-packages = [\"google.protobuf\"]\n\n# By default, packages and members in a package are ordered alphabetically.\n# By setting the member-ordering option to \"preserve\", the original order present in the Protobuf\n# definitions will be preserved.\n# When using the \"preserve\" option and having multiple proto input files, the order of the members will\n# depend not just on the physical order in the Protobuf files, but also on the order in which the files\n# were listed in the input when `protoc` was executed.\n# Default value: \"\"\nmember-ordering = \"preserve\"\n\n# The markdown extensions supported by the main-page-content-file\n# Default value: [\"fenced_code\"]\n# See: https://python-markdown.github.io/extensions/#officially-supported-extensions\nmarkdown-extensions = [\"fenced_code\", \"nl2br\"]\n\n```\n\n### Main page content\n\nCustom introduction content can be specified in a separate file, which can be displayed above the packages list on the main page of the documentation.  \nThen the name of the file has to be specified in the `main-page-content-file` configuration setting.\n\n```toml\nmain-page-content-file = \"intro.md\"\n```\n\nSee the example on the main page of the [demo site](https://markvincze.github.io/sabledocs/demo/).\n\n### Static content\n\nExtra static content, such as additional HTML files or images can be included in the generated output by creating a directory called `static` next to the `sabledocs.toml` file, and copying the static files there.\nAll the files inside the `static` folder will be copied to the _root_ of the generated output (so there won't be a `static` subfolder created).\n\n### Markdown support\n\nMarkdown can be used both in the main content page, and also in the Protobuf comments.  \nCode blocks can be defined both with indentation, and with the ``` fence.\n\n```\n// These are the comments for SearchRequest\n//\n// ```\n// namespace Test\n// {\n//     public class Foo {\n//         public string Bar { get; set; }\n//     }\n// }\n// ```\nmessage SearchRequest {\n  string query = 1;\n  int32 page_number = 2;\n  int32 results_per_page = 3;\n}\n```\n\n(If you include code blocks in a comment, then it's better to use single-line comments (`// ...`) as opposed to block comments (`/* ... */`), because the `protoc` compiler trims all leading whitespace from the lines in block comments, thus the indentation in code blocks gets lost.)\n\n### Customize Jinja templates for primary content\n\nThe `template-path` configuration parameter can be used to specify an alternative directory where the Jinja templates that drive the content of Sabledocs can be found.\nCopy the contents of the `src/sabledocs/templates/_default` from the current version of Sabledocs to the configured directory then edit the templates as necessary. \n\n```toml\ntemplate-path = \"templates\"\n```\n\n### Extra Jinja templates\n\nIf you would like to include your own Jinja templates, specify the `extra-template-path` configuration parameter and\nall files that end in `extra-template-suffix` (default \".html\") will be processed and included as a Jinja template in the output\npath at a location relative to the `extra-template-path`.\n\nAlso processes all subdirectories of `extra-template-path` recursively.  \n\nPrefix a subdirectory with `_` to have it ignored.\n\n```toml\nextra-template-path = \"extra-templates\"\nextra-template-suffix = \".tpl\" # default value is \".html\"\n```\n\n### Custom Parsing of Comments\n\nIn some cases, it may be desirable to implement additional processing on the comment strings before inserting them into the HTML document.\n\nPLEASE NOTE: This is an advanced feature that some have used to embed additional machine-parseable information into a `.proto` file.\nUsers should be aware that use of this feature will probably make it harder to formatting options that `sabledocs` implements, especially those that are white-space sensitive.\n\nIt is activated by indicating a python script defining a class that inherits from [CommentsParser](src/sabledocs/comments_parser.py).\nThis class will be instantiated by `sabledocs` and its methods invoked to pre-process the comment strings that have been collected for\nMessages, Fields, Enums, EnumValues, Services, and ServiceMethods.\nOr, processing of all of these different entities can be indicate by reimplementing `CommentsParser.ParseAll()`.\n\nAn example of using this feature to process comments formatted as JSON strings can be found at [custom_comments_parser.py](sample/custom_comments_parser.py).\n\n```toml\ncomments-parser-file = \"sample/custom_comments_parser.py\"\n```\n\n### Using with Docker\n\nFor convenient usage in CI builds and other scenarios where a Docker image is preferable, the image [`markvincze/sabledocs`](https://hub.docker.com/r/markvincze/sabledocs) can be used, which has both the `protoc` CLI, and `sabledocs` preinstalled.\n\n## For maintainers\n\nBuild the Python package:\n\n```\npython -m build\n```\n\nPublish with twine:\n\n```\npython -m twine upload --repository testpypi dist/*\n```\n\nInstall from the local folder:\n\n```\npip install -e .\n```\n\nBuild the library and the sample documentation, from the `sample` folder:\n\n```\n# PowerShell\nnpm run css-build; pip install ..; sabledocs; .\\output\\index.html\n\n# Bash\nnpm run css-build \u0026\u0026 pip install .. \u0026\u0026 sabledocs \u0026\u0026 .\\output\\index.html\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkvincze%2Fsabledocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkvincze%2Fsabledocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkvincze%2Fsabledocs/lists"}