1*d4726bddSHONG Yifan<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2*d4726bddSHONG Yifan# Rust Doc 3*d4726bddSHONG Yifan 4*d4726bddSHONG Yifan* [rust_doc](#rust_doc) 5*d4726bddSHONG Yifan* [rust_doc_test](#rust_doc_test) 6*d4726bddSHONG Yifan 7*d4726bddSHONG Yifan<a id="rust_doc"></a> 8*d4726bddSHONG Yifan 9*d4726bddSHONG Yifan## rust_doc 10*d4726bddSHONG Yifan 11*d4726bddSHONG Yifan<pre> 12*d4726bddSHONG Yifanrust_doc(<a href="#rust_doc-name">name</a>, <a href="#rust_doc-crate">crate</a>, <a href="#rust_doc-html_after_content">html_after_content</a>, <a href="#rust_doc-html_before_content">html_before_content</a>, <a href="#rust_doc-html_in_header">html_in_header</a>, <a href="#rust_doc-markdown_css">markdown_css</a>, 13*d4726bddSHONG Yifan <a href="#rust_doc-rustc_flags">rustc_flags</a>, <a href="#rust_doc-rustdoc_flags">rustdoc_flags</a>) 14*d4726bddSHONG Yifan</pre> 15*d4726bddSHONG Yifan 16*d4726bddSHONG YifanGenerates code documentation. 17*d4726bddSHONG Yifan 18*d4726bddSHONG YifanExample: 19*d4726bddSHONG YifanSuppose you have the following directory structure for a Rust library crate: 20*d4726bddSHONG Yifan 21*d4726bddSHONG Yifan``` 22*d4726bddSHONG Yifan[workspace]/ 23*d4726bddSHONG Yifan WORKSPACE 24*d4726bddSHONG Yifan hello_lib/ 25*d4726bddSHONG Yifan BUILD 26*d4726bddSHONG Yifan src/ 27*d4726bddSHONG Yifan lib.rs 28*d4726bddSHONG Yifan``` 29*d4726bddSHONG Yifan 30*d4726bddSHONG YifanTo build [`rustdoc`][rustdoc] documentation for the `hello_lib` crate, define a `rust_doc` rule that depends on the the `hello_lib` `rust_library` target: 31*d4726bddSHONG Yifan 32*d4726bddSHONG Yifan[rustdoc]: https://doc.rust-lang.org/book/documentation.html 33*d4726bddSHONG Yifan 34*d4726bddSHONG Yifan```python 35*d4726bddSHONG Yifanpackage(default_visibility = ["//visibility:public"]) 36*d4726bddSHONG Yifan 37*d4726bddSHONG Yifanload("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc") 38*d4726bddSHONG Yifan 39*d4726bddSHONG Yifanrust_library( 40*d4726bddSHONG Yifan name = "hello_lib", 41*d4726bddSHONG Yifan srcs = ["src/lib.rs"], 42*d4726bddSHONG Yifan) 43*d4726bddSHONG Yifan 44*d4726bddSHONG Yifanrust_doc( 45*d4726bddSHONG Yifan name = "hello_lib_doc", 46*d4726bddSHONG Yifan crate = ":hello_lib", 47*d4726bddSHONG Yifan) 48*d4726bddSHONG Yifan``` 49*d4726bddSHONG Yifan 50*d4726bddSHONG YifanRunning `bazel build //hello_lib:hello_lib_doc` will build a zip file containing the documentation for the `hello_lib` library crate generated by `rustdoc`. 51*d4726bddSHONG Yifan 52*d4726bddSHONG Yifan**ATTRIBUTES** 53*d4726bddSHONG Yifan 54*d4726bddSHONG Yifan 55*d4726bddSHONG Yifan| Name | Description | Type | Mandatory | Default | 56*d4726bddSHONG Yifan| :------------- | :------------- | :------------- | :------------- | :------------- | 57*d4726bddSHONG Yifan| <a id="rust_doc-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 58*d4726bddSHONG Yifan| <a id="rust_doc-crate"></a>crate | The label of the target to generate code documentation for.<br><br>`rust_doc` can generate HTML code documentation for the source files of `rust_library` or `rust_binary` targets. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 59*d4726bddSHONG Yifan| <a id="rust_doc-html_after_content"></a>html_after_content | File to add in `<body>`, after content. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 60*d4726bddSHONG Yifan| <a id="rust_doc-html_before_content"></a>html_before_content | File to add in `<body>`, before content. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 61*d4726bddSHONG Yifan| <a id="rust_doc-html_in_header"></a>html_in_header | File to add to `<head>`. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 62*d4726bddSHONG Yifan| <a id="rust_doc-markdown_css"></a>markdown_css | CSS files to include via `<link>` in a rendered Markdown file. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 63*d4726bddSHONG Yifan| <a id="rust_doc-rustc_flags"></a>rustc_flags | **Deprecated**: use `rustdoc_flags` instead | List of strings | optional | `[]` | 64*d4726bddSHONG Yifan| <a id="rust_doc-rustdoc_flags"></a>rustdoc_flags | List of flags passed to `rustdoc`.<br><br>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 | `[]` | 65*d4726bddSHONG Yifan 66*d4726bddSHONG Yifan 67*d4726bddSHONG Yifan<a id="rust_doc_test"></a> 68*d4726bddSHONG Yifan 69*d4726bddSHONG Yifan## rust_doc_test 70*d4726bddSHONG Yifan 71*d4726bddSHONG Yifan<pre> 72*d4726bddSHONG Yifanrust_doc_test(<a href="#rust_doc_test-name">name</a>, <a href="#rust_doc_test-deps">deps</a>, <a href="#rust_doc_test-crate">crate</a>) 73*d4726bddSHONG Yifan</pre> 74*d4726bddSHONG Yifan 75*d4726bddSHONG YifanRuns Rust documentation tests. 76*d4726bddSHONG Yifan 77*d4726bddSHONG YifanExample: 78*d4726bddSHONG Yifan 79*d4726bddSHONG YifanSuppose you have the following directory structure for a Rust library crate: 80*d4726bddSHONG Yifan 81*d4726bddSHONG Yifan```output 82*d4726bddSHONG Yifan[workspace]/ 83*d4726bddSHONG YifanWORKSPACE 84*d4726bddSHONG Yifanhello_lib/ 85*d4726bddSHONG Yifan BUILD 86*d4726bddSHONG Yifan src/ 87*d4726bddSHONG Yifan lib.rs 88*d4726bddSHONG Yifan``` 89*d4726bddSHONG Yifan 90*d4726bddSHONG YifanTo 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: 91*d4726bddSHONG Yifan 92*d4726bddSHONG Yifan[doc-test]: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests 93*d4726bddSHONG Yifan 94*d4726bddSHONG Yifan```python 95*d4726bddSHONG Yifanpackage(default_visibility = ["//visibility:public"]) 96*d4726bddSHONG Yifan 97*d4726bddSHONG Yifanload("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test") 98*d4726bddSHONG Yifan 99*d4726bddSHONG Yifanrust_library( 100*d4726bddSHONG Yifan name = "hello_lib", 101*d4726bddSHONG Yifan srcs = ["src/lib.rs"], 102*d4726bddSHONG Yifan) 103*d4726bddSHONG Yifan 104*d4726bddSHONG Yifanrust_doc_test( 105*d4726bddSHONG Yifan name = "hello_lib_doc_test", 106*d4726bddSHONG Yifan crate = ":hello_lib", 107*d4726bddSHONG Yifan) 108*d4726bddSHONG Yifan``` 109*d4726bddSHONG Yifan 110*d4726bddSHONG YifanRunning `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate. 111*d4726bddSHONG Yifan 112*d4726bddSHONG Yifan**ATTRIBUTES** 113*d4726bddSHONG Yifan 114*d4726bddSHONG Yifan 115*d4726bddSHONG Yifan| Name | Description | Type | Mandatory | Default | 116*d4726bddSHONG Yifan| :------------- | :------------- | :------------- | :------------- | :------------- | 117*d4726bddSHONG Yifan| <a id="rust_doc_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 118*d4726bddSHONG Yifan| <a id="rust_doc_test-deps"></a>deps | List of other libraries to be linked to this library target.<br><br>These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 119*d4726bddSHONG Yifan| <a id="rust_doc_test-crate"></a>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. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 120*d4726bddSHONG Yifan 121*d4726bddSHONG Yifan 122