Documentation¶
Rules for generating protobuf Markdown, JSON, HTML or DocBook documentation with protoc-gen-doc
Rule |
Description |
---|---|
Generates DocBook |
|
Generates |
|
Generates |
|
Generates Markdown |
|
Generates documentation file using Go template file |
doc_docbook_compile¶
Generates DocBook .xml
documentation file
Example¶
Full example project can be found here
WORKSPACE
¶
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
rules_proto_grpc_doc_repos()
BUILD.bazel
¶
load("@rules_proto_grpc//doc:defs.bzl", "doc_docbook_compile")
doc_docbook_compile(
name = "person_doc_proto",
protos = ["@rules_proto_grpc//example/proto:person_proto"],
)
doc_docbook_compile(
name = "place_doc_proto",
protos = ["@rules_proto_grpc//example/proto:place_proto"],
)
doc_docbook_compile(
name = "thing_doc_proto",
protos = ["@rules_proto_grpc//example/proto:thing_proto"],
)
Attributes¶
Name |
Type |
Mandatory |
Default |
Description |
---|---|---|---|---|
|
|
true |
List of labels that provide the |
|
|
|
false |
|
Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins |
|
|
false |
|
The verbosity level. Supported values and results are 0: Show nothing, 1: Show command, 2: Show command and sandbox after running protoc, 3: Show command and sandbox before and after running protoc, 4. Show env, command, expected outputs and sandbox before and after running protoc |
|
|
false |
|
Path to prefix to the generated files in the output directory |
|
|
false |
|
A list of extra args to pass directly to protoc, not as plugin options |
|
|
false |
|
List of labels that provide extra files to be available during protoc execution |
|
|
false |
|
The output mode for the target. PREFIXED (the default) will output to a directory named by the target within the current package root, NO_PREFIX will output directly to the current package. Using NO_PREFIX may lead to conflicting writes |
Plugins¶
doc_html_compile¶
Generates .html
documentation file
Example¶
Full example project can be found here
WORKSPACE
¶
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
rules_proto_grpc_doc_repos()
BUILD.bazel
¶
load("@rules_proto_grpc//doc:defs.bzl", "doc_html_compile")
doc_html_compile(
name = "person_doc_proto",
protos = ["@rules_proto_grpc//example/proto:person_proto"],
)
doc_html_compile(
name = "place_doc_proto",
protos = ["@rules_proto_grpc//example/proto:place_proto"],
)
doc_html_compile(
name = "thing_doc_proto",
protos = ["@rules_proto_grpc//example/proto:thing_proto"],
)
Attributes¶
Name |
Type |
Mandatory |
Default |
Description |
---|---|---|---|---|
|
|
true |
List of labels that provide the |
|
|
|
false |
|
Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins |
|
|
false |
|
The verbosity level. Supported values and results are 0: Show nothing, 1: Show command, 2: Show command and sandbox after running protoc, 3: Show command and sandbox before and after running protoc, 4. Show env, command, expected outputs and sandbox before and after running protoc |
|
|
false |
|
Path to prefix to the generated files in the output directory |
|
|
false |
|
A list of extra args to pass directly to protoc, not as plugin options |
|
|
false |
|
List of labels that provide extra files to be available during protoc execution |
|
|
false |
|
The output mode for the target. PREFIXED (the default) will output to a directory named by the target within the current package root, NO_PREFIX will output directly to the current package. Using NO_PREFIX may lead to conflicting writes |
Plugins¶
doc_json_compile¶
Generates .json
documentation file
Example¶
Full example project can be found here
WORKSPACE
¶
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
rules_proto_grpc_doc_repos()
BUILD.bazel
¶
load("@rules_proto_grpc//doc:defs.bzl", "doc_json_compile")
doc_json_compile(
name = "person_doc_proto",
protos = ["@rules_proto_grpc//example/proto:person_proto"],
)
doc_json_compile(
name = "place_doc_proto",
protos = ["@rules_proto_grpc//example/proto:place_proto"],
)
doc_json_compile(
name = "thing_doc_proto",
protos = ["@rules_proto_grpc//example/proto:thing_proto"],
)
Attributes¶
Name |
Type |
Mandatory |
Default |
Description |
---|---|---|---|---|
|
|
true |
List of labels that provide the |
|
|
|
false |
|
Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins |
|
|
false |
|
The verbosity level. Supported values and results are 0: Show nothing, 1: Show command, 2: Show command and sandbox after running protoc, 3: Show command and sandbox before and after running protoc, 4. Show env, command, expected outputs and sandbox before and after running protoc |
|
|
false |
|
Path to prefix to the generated files in the output directory |
|
|
false |
|
A list of extra args to pass directly to protoc, not as plugin options |
|
|
false |
|
List of labels that provide extra files to be available during protoc execution |
|
|
false |
|
The output mode for the target. PREFIXED (the default) will output to a directory named by the target within the current package root, NO_PREFIX will output directly to the current package. Using NO_PREFIX may lead to conflicting writes |
Plugins¶
doc_markdown_compile¶
Generates Markdown .md
documentation file
Example¶
Full example project can be found here
WORKSPACE
¶
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
rules_proto_grpc_doc_repos()
BUILD.bazel
¶
load("@rules_proto_grpc//doc:defs.bzl", "doc_markdown_compile")
doc_markdown_compile(
name = "person_doc_proto",
protos = ["@rules_proto_grpc//example/proto:person_proto"],
)
doc_markdown_compile(
name = "place_doc_proto",
protos = ["@rules_proto_grpc//example/proto:place_proto"],
)
doc_markdown_compile(
name = "thing_doc_proto",
protos = ["@rules_proto_grpc//example/proto:thing_proto"],
)
Attributes¶
Name |
Type |
Mandatory |
Default |
Description |
---|---|---|---|---|
|
|
true |
List of labels that provide the |
|
|
|
false |
|
Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins |
|
|
false |
|
The verbosity level. Supported values and results are 0: Show nothing, 1: Show command, 2: Show command and sandbox after running protoc, 3: Show command and sandbox before and after running protoc, 4. Show env, command, expected outputs and sandbox before and after running protoc |
|
|
false |
|
Path to prefix to the generated files in the output directory |
|
|
false |
|
A list of extra args to pass directly to protoc, not as plugin options |
|
|
false |
|
List of labels that provide extra files to be available during protoc execution |
|
|
false |
|
The output mode for the target. PREFIXED (the default) will output to a directory named by the target within the current package root, NO_PREFIX will output directly to the current package. Using NO_PREFIX may lead to conflicting writes |
Plugins¶
doc_template_compile¶
Warning
This rule is experimental. It may not work correctly or may change in future releases!
Generates documentation file using Go template file
Example¶
Full example project can be found here
WORKSPACE
¶
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
rules_proto_grpc_doc_repos()
BUILD.bazel
¶
load("@rules_proto_grpc//doc:defs.bzl", "doc_template_compile")
doc_template_compile(
name = "greeter_doc_proto.txt",
output_mode = "NO_PREFIX",
protos = [
"@rules_proto_grpc//example/proto:greeter_grpc",
"@rules_proto_grpc//example/proto:thing_proto",
],
template = "template.txt",
)
Attributes¶
Name |
Type |
Mandatory |
Default |
Description |
---|---|---|---|---|
|
|
true |
List of labels that provide the |
|
|
|
false |
|
Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins |
|
|
false |
|
The verbosity level. Supported values and results are 0: Show nothing, 1: Show command, 2: Show command and sandbox after running protoc, 3: Show command and sandbox before and after running protoc, 4. Show env, command, expected outputs and sandbox before and after running protoc |
|
|
false |
|
Path to prefix to the generated files in the output directory |
|
|
false |
|
A list of extra args to pass directly to protoc, not as plugin options |
|
|
false |
|
List of labels that provide extra files to be available during protoc execution |
|
|
false |
|
The output mode for the target. PREFIXED (the default) will output to a directory named by the target within the current package root, NO_PREFIX will output directly to the current package. Using NO_PREFIX may lead to conflicting writes |
|
|
true |
|
The documentation template file. |