Skip to content

Commit

Permalink
stardoc: Use backtick not <code> for attr default values (bazelbuil…
Browse files Browse the repository at this point in the history 
…d#1682)

* stardoc: Use backtick not `<code>` for attr default values

This is a cherry-pick of bazelbuild/stardoc#143

* Regenerate documentation
  • Loading branch information
@illicitonion
illicitonion authored Nov 30, 2022
1 parent d4b31a4 commit 5623741
Show file tree
Hide file tree
Showing 15 changed files with 666 additions and 639 deletions.
10 changes: 7 additions & 3 deletions docs/WORKSPACE.bazel
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,14 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
name = "io_bazel_stardoc",
sha256 = "aa814dae0ac400bbab2e8881f9915c6f47c49664bf087c409a15f90438d2c23e",
patches = [
# Pull in https://github.com/bazelbuild/stardoc/pull/143
"//:stardoc-attr-default-wrappers.patch",
],
sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.1/stardoc-0.5.1.tar.gz",
"https://github.com/bazelbuild/stardoc/releases/download/0.5.1/stardoc-0.5.1.tar.gz",
"https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
"https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
],
)

Expand Down
56 changes: 28 additions & 28 deletions docs/cargo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,20 +23,20 @@ A rule for bootstrapping a Rust binary using [Cargo](https://doc.rust-lang.org/c

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="cargo_bootstrap_repository-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a id="cargo_bootstrap_repository-binary"></a>binary | The binary to build (the <code>--bin</code> parameter for Cargo). If left empty, the repository name will be used. | String | optional | "" |
| <a id="cargo_bootstrap_repository-build_mode"></a>build_mode | The build mode the binary should be built with | String | optional | "release" |
| <a id="cargo_bootstrap_repository-cargo_lockfile"></a>cargo_lockfile | The lockfile of the crate_universe resolver | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="cargo_bootstrap_repository-cargo_toml"></a>cargo_toml | The path of the crate_universe resolver manifest (<code>Cargo.toml</code> file) | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="cargo_bootstrap_repository-env"></a>env | A mapping of platform triple to a set of environment variables. See [cargo_env](#cargo_env) for usage details. Additionally, the platform triple <code>*</code> applies to all platforms. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="cargo_bootstrap_repository-env_label"></a>env_label | A mapping of platform triple to a set of environment variables. This attribute differs from <code>env</code> in that all variables passed here must be fully qualified labels of files. See [cargo_env](#cargo_env) for usage details. Additionally, the platform triple <code>*</code> applies to all platforms. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="cargo_bootstrap_repository-iso_date"></a>iso_date | The iso_date of cargo binary the resolver should use. Note: This can only be set if <code>version</code> is <code>beta</code> or <code>nightly</code> | String | optional | "" |
| <a id="cargo_bootstrap_repository-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>). | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | required | |
| <a id="cargo_bootstrap_repository-rust_toolchain_cargo_template"></a>rust_toolchain_cargo_template | The template to use for finding the host <code>cargo</code> binary. <code>{version}</code> (eg. '1.53.0'), <code>{triple}</code> (eg. 'x86_64-unknown-linux-gnu'), <code>{arch}</code> (eg. 'aarch64'), <code>{vendor}</code> (eg. 'unknown'), <code>{system}</code> (eg. 'darwin'), and <code>{tool}</code> (eg. 'rustc.exe') will be replaced in the string if present. | String | optional | "@rust_{system}_{arch}__{triple}_tools//:bin/{tool}" |
| <a id="cargo_bootstrap_repository-rust_toolchain_rustc_template"></a>rust_toolchain_rustc_template | The template to use for finding the host <code>rustc</code> binary. <code>{version}</code> (eg. '1.53.0'), <code>{triple}</code> (eg. 'x86_64-unknown-linux-gnu'), <code>{arch}</code> (eg. 'aarch64'), <code>{vendor}</code> (eg. 'unknown'), <code>{system}</code> (eg. 'darwin'), and <code>{tool}</code> (eg. 'rustc.exe') will be replaced in the string if present. | String | optional | "@rust_{system}_{arch}__{triple}_tools//:bin/{tool}" |
| <a id="cargo_bootstrap_repository-srcs"></a>srcs | Souce files of the crate to build. Passing source files here can be used to trigger rebuilds when changes are made | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="cargo_bootstrap_repository-timeout"></a>timeout | Maximum duration of the Cargo build command in seconds | Integer | optional | 600 |
| <a id="cargo_bootstrap_repository-version"></a>version | The version of cargo the resolver should use | String | optional | "1.65.0" |
| <a id="cargo_bootstrap_repository-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="cargo_bootstrap_repository-binary"></a>binary | The binary to build (the <code>--bin</code> parameter for Cargo). If left empty, the repository name will be used. | String | optional | <code>""</code> |
| <a id="cargo_bootstrap_repository-build_mode"></a>build_mode | The build mode the binary should be built with | String | optional | <code>"release"</code> |
| <a id="cargo_bootstrap_repository-cargo_lockfile"></a>cargo_lockfile | The lockfile of the crate_universe resolver | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
| <a id="cargo_bootstrap_repository-cargo_toml"></a>cargo_toml | The path of the crate_universe resolver manifest (<code>Cargo.toml</code> file) | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
| <a id="cargo_bootstrap_repository-env"></a>env | A mapping of platform triple to a set of environment variables. See [cargo_env](#cargo_env) for usage details. Additionally, the platform triple <code>*</code> applies to all platforms. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> |
| <a id="cargo_bootstrap_repository-env_label"></a>env_label | A mapping of platform triple to a set of environment variables. This attribute differs from <code>env</code> in that all variables passed here must be fully qualified labels of files. See [cargo_env](#cargo_env) for usage details. Additionally, the platform triple <code>*</code> applies to all platforms. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> |
| <a id="cargo_bootstrap_repository-iso_date"></a>iso_date | The iso_date of cargo binary the resolver should use. Note: This can only be set if <code>version</code> is <code>beta</code> or <code>nightly</code> | String | optional | <code>""</code> |
| <a id="cargo_bootstrap_repository-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="cargo_bootstrap_repository-rust_toolchain_cargo_template"></a>rust_toolchain_cargo_template | The template to use for finding the host <code>cargo</code> binary. <code>{version}</code> (eg. '1.53.0'), <code>{triple}</code> (eg. 'x86_64-unknown-linux-gnu'), <code>{arch}</code> (eg. 'aarch64'), <code>{vendor}</code> (eg. 'unknown'), <code>{system}</code> (eg. 'darwin'), and <code>{tool}</code> (eg. 'rustc.exe') will be replaced in the string if present. | String | optional | <code>"@rust_{system}_{arch}__{triple}_tools//:bin/{tool}"</code> |
| <a id="cargo_bootstrap_repository-rust_toolchain_rustc_template"></a>rust_toolchain_rustc_template | The template to use for finding the host <code>rustc</code> binary. <code>{version}</code> (eg. '1.53.0'), <code>{triple}</code> (eg. 'x86_64-unknown-linux-gnu'), <code>{arch}</code> (eg. 'aarch64'), <code>{vendor}</code> (eg. 'unknown'), <code>{system}</code> (eg. 'darwin'), and <code>{tool}</code> (eg. 'rustc.exe') will be replaced in the string if present. | String | optional | <code>"@rust_{system}_{arch}__{triple}_tools//:bin/{tool}"</code> |
| <a id="cargo_bootstrap_repository-srcs"></a>srcs | Souce files of the crate to build. Passing source files here can be used to trigger rebuilds when changes are made | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
| <a id="cargo_bootstrap_repository-timeout"></a>timeout | Maximum duration of the Cargo build command in seconds | Integer | optional | <code>600</code> |
| <a id="cargo_bootstrap_repository-version"></a>version | The version of cargo the resolver should use | String | optional | <code>"1.65.0"</code> |


<a id="cargo_dep_env"></a>
Expand All @@ -54,9 +54,9 @@ A rule for generating variables for dependent `cargo_build_script`s without a bu

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="cargo_dep_env-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a id="cargo_dep_env-out_dir"></a>out_dir | Folder containing additional inputs when building all direct dependencies.<br><br>This has the same effect as a <code>cargo_build_script</code> which prints puts files into <code>$OUT_DIR</code>, but without requiring a build script. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="cargo_dep_env-src"></a>src | File containing additional environment variables to set for build scripts of direct dependencies.<br><br>This has the same effect as a <code>cargo_build_script</code> which prints <code>cargo:VAR=VALUE</code> lines, but without requiring a build script.<br><br>This files should contain a single variable per line, of format <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>). | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="cargo_dep_env-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="cargo_dep_env-out_dir"></a>out_dir | Folder containing additional inputs when building all direct dependencies.<br><br>This has the same effect as a <code>cargo_build_script</code> which prints puts files into <code>$OUT_DIR</code>, but without requiring a build script. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
| <a id="cargo_dep_env-src"></a>src | File containing additional environment variables to set for build scripts of direct dependencies.<br><br>This has the same effect as a <code>cargo_build_script</code> which prints <code>cargo:VAR=VALUE</code> lines, but without requiring a build script.<br><br>This files should contain a single variable per line, of format <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>). | <a href="https://bazel.build/concepts/labels">Label</a> | required | |


<a id="cargo_build_script"></a>
Expand Down Expand Up @@ -132,17 +132,17 @@ The `hello_lib` target will be build with the flags and the environment variable
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="cargo_build_script-name"></a>name | The name for the underlying rule. This should be the name of the package being compiled, optionally with a suffix of <code>_build_script</code>. | none |
| <a id="cargo_build_script-crate_features"></a>crate_features | A list of features to enable for the build script. | <code>[]</code> |
| <a id="cargo_build_script-version"></a>version | The semantic version (semver) of the crate. | <code>None</code> |
| <a id="cargo_build_script-deps"></a>deps | The dependencies of the crate. | <code>[]</code> |
| <a id="cargo_build_script-build_script_env"></a>build_script_env | Environment variables for build scripts. | <code>{}</code> |
| <a id="cargo_build_script-data"></a>data | Files needed by the build script. | <code>[]</code> |
| <a id="cargo_build_script-tools"></a>tools | Tools (executables) needed by the build script. | <code>[]</code> |
| <a id="cargo_build_script-links"></a>links | Name of the native library this crate links against. | <code>None</code> |
| <a id="cargo_build_script-rustc_env"></a>rustc_env | Environment variables to set in rustc when compiling the build script. | <code>{}</code> |
| <a id="cargo_build_script-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>. | <code>[]</code> |
| <a id="cargo_build_script-visibility"></a>visibility | Visibility to apply to the generated build script output. | <code>None</code> |
| <a id="cargo_build_script-tags"></a>tags | (list of str, optional): Tags to apply to the generated build script output. | <code>None</code> |
| <a id="cargo_build_script-crate_features"></a>crate_features | A list of features to enable for the build script. | `[]` |
| <a id="cargo_build_script-version"></a>version | The semantic version (semver) of the crate. | `None` |
| <a id="cargo_build_script-deps"></a>deps | The dependencies of the crate. | `[]` |
| <a id="cargo_build_script-build_script_env"></a>build_script_env | Environment variables for build scripts. | `{}` |
| <a id="cargo_build_script-data"></a>data | Files needed by the build script. | `[]` |
| <a id="cargo_build_script-tools"></a>tools | Tools (executables) needed by the build script. | `[]` |
| <a id="cargo_build_script-links"></a>links | Name of the native library this crate links against. | `None` |
| <a id="cargo_build_script-rustc_env"></a>rustc_env | Environment variables to set in rustc when compiling the build script. | `{}` |
| <a id="cargo_build_script-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>. | `[]` |
| <a id="cargo_build_script-visibility"></a>visibility | Visibility to apply to the generated build script output. | `None` |
| <a id="cargo_build_script-tags"></a>tags | (list of str, optional): Tags to apply to the generated build script output. | `None` |
| <a id="cargo_build_script-kwargs"></a>kwargs | Forwards to the underlying <code>rust_binary</code> rule. | none |


Expand Down
Loading

0 comments on commit 5623741

Please sign in to comment.