Generates code documentation.
Example:
Suppose you have the following directory structure for a Rust library crate:
```
[workspace]/
WORKSPACE
hello_lib/
BUILD
src/
lib.rs
```
To build [`rustdoc`][rustdoc] documentation for the `hello_lib` crate, define a `rust_doc` rule that depends on the the `hello_lib` `rust_library` target:
[rustdoc]: https://doc.rust-lang.org/book/documentation.html
```python
package(default_visibility = ["//visibility:public"])
load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc")
rust_library(
name = "hello_lib",
srcs = ["src/lib.rs"],
)
rust_doc(
name = "hello_lib_doc",
crate = ":hello_lib",
)
```
Running `bazel build //hello_lib:hello_lib_doc` will build a zip file containing the documentation for the `hello_lib` library crate generated by `rustdoc`.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| crate | The label of the target to generate code documentation for.
`rust_doc` can generate HTML code documentation for the source files of `rust_library` or `rust_binary` targets. | Label | required | |
| html_after_content | File to add in ``, after content. | Label | optional | `None` |
| html_before_content | File to add in ``, before content. | Label | optional | `None` |
| html_in_header | File to add to ``. | Label | optional | `None` |
| markdown_css | CSS files to include via `` in a rendered Markdown file. | List of labels | optional | `[]` |
| rustc_flags | **Deprecated**: use `rustdoc_flags` instead | List of strings | optional | `[]` |
| rustdoc_flags | List of flags passed to `rustdoc`.
These strings are subject to Make variable expansion for predefined source/output path variables like `$location`, `$execpath`, and `$rootpath`. This expansion is useful if you wish to pass a generated file of arguments to rustc: `@$(location //package:target)`. | List of strings | optional | `[]` |
## rust_doc_test
Runs Rust documentation tests.
Example:
Suppose you have the following directory structure for a Rust library crate:
```output
[workspace]/
WORKSPACE
hello_lib/
BUILD
src/
lib.rs
```
To run [documentation tests][doc-test] for the `hello_lib` crate, define a `rust_doc_test` target that depends on the `hello_lib` `rust_library` target:
[doc-test]: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests
```python
package(default_visibility = ["//visibility:public"])
load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test")
rust_library(
name = "hello_lib",
srcs = ["src/lib.rs"],
)
rust_doc_test(
name = "hello_lib_doc_test",
crate = ":hello_lib",
)
```
Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| deps | List of other libraries to be linked to this library target.
These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | List of labels | optional | `[]` |
| crate | The label of the target to generate code documentation for. `rust_doc_test` can generate HTML code documentation for the source files of `rust_library` or `rust_binary` targets. | Label | required | |