| Name | sabledocs JSON |
| Version |
0.15.871
JSON |
| download |
| home_page | None |
| Summary | Static documentation generator for Protobuf and gRPC |
| upload_time | 2025-01-12 16:03:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11.0 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# [Sabledocs](https://markvincze.github.io/sabledocs/)
[](https://dl.circleci.com/status-badge/redirect/gh/markvincze/sabledocs/tree/main)
[](https://pypi.org/project/sabledocs/)
[](https://pypi.org/project/sabledocs/)
A simple static documentation generator for Protobuf and gRPC contracts.
**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).
## 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](https://github.com/protocolbuffers/protobuf/releases) 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](https://www.python.org/downloads/) (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.
```toml
# 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.
# They are used to generate deeplinks for the members 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 three possible values, "github", "bitbucket" and "gitlab".
# The fields repository-url and repository-branch should be configured to point to the correct repository.
# repository-dir should be set only if the root of your Protobuf module is in a specific directory inside your repository.
repository-type = "github"
repository-url = "https://github.com/janedoe/myawesomeproject"
repository-branch = "main"
repository-dir = "proto"
# 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"]
# Packages can be hidden from the generated documentation by adding them to the hidden-packages
# collection. In the templates, the field non_hidden_packages can be used to access the packages which are
# not listed in hidden-packages. (And the packages field returns all packages.)
# Default value: []
hidden-packages = ["google.protobuf"]
# By default, packages and members in a package are ordered alphabetically.
# By setting the member-ordering option to "preserve", the original order present in the Protobuf
# definitions will be preserved.
# When using the "preserve" option and having multiple proto input files, the order of the members will
# depend not just on the physical order in the Protobuf files, but also on the order in which the files
# were listed in the input when `protoc` was executed.
# Default value: ""
member-ordering = "preserve"
# The markdown extensions supported by the main-page-content-file
# Default value: ["fenced_code"]
# See: https://python-markdown.github.io/extensions/#officially-supported-extensions
markdown-extensions = ["fenced_code", "nl2br"]
```
### 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.
```toml
main-page-content-file = "intro.md"
```
See the example on the main page of the [demo site](https://markvincze.github.io/sabledocs/demo/).
### Static content
Extra 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.
All 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).
### Markdown support
Markdown can be used both in the main content page, and also in the Protobuf comments.
Code blocks can be defined both with indentation, and with the ``` fence.
```
// These are the comments for SearchRequest
//
// ```
// namespace Test
// {
// public class Foo {
// public string Bar { get; set; }
// }
// }
// ```
message SearchRequest {
string query = 1;
int32 page_number = 2;
int32 results_per_page = 3;
}
```
(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.)
### Customize Jinja templates for primary content
The `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.
Copy the contents of the `src/sabledocs/templates/_default` from the current version of Sabledocs to the configured directory then edit the templates as necessary.
```toml
template-path = "templates"
```
### Extra Jinja templates
If you would like to include your own Jinja templates, specify the `extra-template-path` configuration parameter and
all files that end in `template-path-suffix` (default ".html") will be processed and included as a Jinja template in the output
path at a location relative to the `extra-template-path`.
Also processes all subdirectories of `extra-template-path` recursively.
Prefix a subdirectory with `_` to have it ignored.
```toml
template-path = "extra-templates"
template-path-suffix = ".tpl" # default value is ".html"
```
### Custom Parsing of Comments
In some cases, it may be desirable to implement additional processing on the comment strings before inserting them into the HTML document.
PLEASE NOTE: This is an advanced feature that some have used to embed additional machine-parseable information into a `.proto` file.
Users 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.
It is activated by indicating a python script defining a class that inherits from [CommentsParser](src/sabledocs/comments_parser.py).
This class will be instantiated by `sabledocs` and its methods invoked to pre-process the comment strings that have been collected for
Messages, Fields, Enums, EnumValues, Services, and ServiceMethods.
Or, processing of all of these different entities can be indicate by reimplementing `CommentsParser.ParseAll()`.
An 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).
```toml
comments-parser-file = "sample/custom_comments_parser.py"
```
### Using with Docker
For 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.
## 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 -e .
```
Build the library and the sample documentation, from the `sample` folder:
```
# PowerShell
npm run css-build; pip install ..; sabledocs; .\output\index.html
# Bash
npm run css-build && pip install .. && sabledocs && .\output\index.html
```
Raw data
{
"_id": null,
"home_page": null,
"name": "sabledocs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11.0",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Mark Vincze <mrk.vincze@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/79/07/52ea95f72992c08c11c8b270fa3c5746c29c2fade4c34451c86cfacfd148/sabledocs-0.15.871.tar.gz",
"platform": null,
"description": "# [Sabledocs](https://markvincze.github.io/sabledocs/)\n\n[](https://dl.circleci.com/status-badge/redirect/gh/markvincze/sabledocs/tree/main)\n[](https://pypi.org/project/sabledocs/)\n[](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 = \"\u00a9 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 three possible values, \"github\", \"bitbucket\" 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 `template-path-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\ntemplate-path = \"extra-templates\"\ntemplate-path-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 && pip install .. && sabledocs && .\\output\\index.html\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Static documentation generator for Protobuf and gRPC",
"version": "0.15.871",
"project_urls": {
"Bug Tracker": "https://github.com/markvincze/sabledocs/issues",
"Homepage": "https://github.com/markvincze/sabledocs"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "08b9c4740588e543012b13bd8c17de5828e94f57ff8acd445f6a9415407432f3",
"md5": "e308f590e43909ca284bc579fcc5d0b1",
"sha256": "1e150249b439249e244d945f5d0d3d409aa18171818f32d0523289d55eaf2ffe"
},
"downloads": -1,
"filename": "sabledocs-0.15.871-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e308f590e43909ca284bc579fcc5d0b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11.0",
"size": 85918,
"upload_time": "2025-01-12T16:03:49",
"upload_time_iso_8601": "2025-01-12T16:03:49.394991Z",
"url": "https://files.pythonhosted.org/packages/08/b9/c4740588e543012b13bd8c17de5828e94f57ff8acd445f6a9415407432f3/sabledocs-0.15.871-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "790752ea95f72992c08c11c8b270fa3c5746c29c2fade4c34451c86cfacfd148",
"md5": "876b2122fbe9d85e1bdeb68a1f97fcfe",
"sha256": "29f159c7e4be34305acde748fd1d74a4cb760b38243518c4a8998b85fddb68cb"
},
"downloads": -1,
"filename": "sabledocs-0.15.871.tar.gz",
"has_sig": false,
"md5_digest": "876b2122fbe9d85e1bdeb68a1f97fcfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11.0",
"size": 85237,
"upload_time": "2025-01-12T16:03:50",
"upload_time_iso_8601": "2025-01-12T16:03:50.769289Z",
"url": "https://files.pythonhosted.org/packages/79/07/52ea95f72992c08c11c8b270fa3c5746c29c2fade4c34451c86cfacfd148/sabledocs-0.15.871.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-12 16:03:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "markvincze",
"github_project": "sabledocs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "sabledocs"
}
