Added test script for ensuring docs are up to date. (bazelbuild#672)

* Added test script for ensuring docs are up to date. * Fixed bug in doc attribute formatting. * Regenerate documentation * `_tidy` now ignores empty first lines * Updated comment * Regenerate documentation
yagehu · Apr 23, 2021 · 5e56f02 · 5e56f02
1 parent abe6bff
commit 5e56f02
Show file tree

Hide file tree

Showing 9 changed files with 397 additions and 312 deletions.
diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml
@@ -1,12 +1,12 @@
 ---
 default_linux_targets: &default_linux_targets
-- "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
-- "..."
-- "@examples//..."
-# TODO: Switch manual tag to platform constraint after bazel 4.0.
-- "//test/versioned_dylib:versioned_dylib_test"
-# Bindgen currently only has a working toolchain for 18.04
-- "-@examples//ffi/rust_calling_c/simple/..."
+  - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
+  - "..."
+  - "@examples//..."
+  # TODO: Switch manual tag to platform constraint after bazel 4.0.
+  - "//test/versioned_dylib:versioned_dylib_test"
+  # Bindgen currently only has a working toolchain for 18.04
+  - "-@examples//ffi/rust_calling_c/simple/..."
 tasks:
   ubuntu1604:
     build_targets: *default_linux_targets
@@ -25,85 +25,81 @@ tasks:
     test_targets: *default_linux_targets
   macos:
     osx_targets: &osx_targets
-    - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
-    - "..."
-    - "@examples//..."
-    # Skip tests for dylib support on osx, since we don't support it yet.
-    - "-@examples//ffi/rust_calling_c:matrix_dylib_test"
-    - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked"
-    - "-@examples//ffi/rust_calling_c/simple/..."
+      - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
+      - "..."
+      - "@examples//..."
+      # Skip tests for dylib support on osx, since we don't support it yet.
+      - "-@examples//ffi/rust_calling_c:matrix_dylib_test"
+      - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked"
+      - "-@examples//ffi/rust_calling_c/simple/..."
     build_targets: *osx_targets
     test_targets: *osx_targets
   rbe_ubuntu1604:
     test_targets:
-    - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
-    - "..."
-    - "//test/..."
-    - "@examples//..."
-    - "-//test/conflicting_deps:conflicting_deps_test"
-    # rust_doc_test is likely not fully sandboxed
-    - "-//test/chained_direct_deps:mod3_doc_test"
-    - "-@examples//fibonacci:fibonacci_doc_test"
-    - "-@examples//hello_lib:hello_lib_doc_test"
-    - "-//tools/runfiles:runfiles_doc_test"
-    - "-@examples//ffi/rust_calling_c/simple/..."
-    # See https://github.com/bazelbuild/bazel/issues/9987
-    - "-@examples//ffi/rust_calling_c:matrix_dylib_test"
+      - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
+      - "..."
+      - "//test/..."
+      - "@examples//..."
+      - "-//test/conflicting_deps:conflicting_deps_test"
+      # rust_doc_test is likely not fully sandboxed
+      - "-//test/chained_direct_deps:mod3_doc_test"
+      - "-@examples//fibonacci:fibonacci_doc_test"
+      - "-@examples//hello_lib:hello_lib_doc_test"
+      - "-//tools/runfiles:runfiles_doc_test"
+      - "-@examples//ffi/rust_calling_c/simple/..."
+      # See https://github.com/bazelbuild/bazel/issues/9987
+      - "-@examples//ffi/rust_calling_c:matrix_dylib_test"
   windows:
     build_flags:
-    - "--enable_runfiles" # this is not enabled by default on windows and is necessary for the cargo build scripts
+      - "--enable_runfiles" # this is not enabled by default on windows and is necessary for the cargo build scripts
     windows_targets: &windows_targets
-    - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
-    - "..."
-    - "-//bindgen/..."
-    - "-//test/load_arbitrary_tool/..."
-    - "-//test/test_env/..."
-    - "-//test/proto/..."
-    - "-//tools/rust_analyzer/..."
-    - "-//tools/runfiles/..."
-    - "-//test/rustfmt/..."
-    - "@examples//..."
-    - "-@examples//ffi/rust_calling_c:matrix_dylib_test"
-    - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked"
-    - "-@examples//ffi/rust_calling_c/simple/..."
-    - "-@examples//hello_sys/..."
-    - "-@examples//complex_sys/..."
-    - "-@examples//proto/..."
-    - "-@examples//wasm/..."
+      - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245
+      - "..."
+      - "-//bindgen/..."
+      - "-//test/load_arbitrary_tool/..."
+      - "-//test/test_env/..."
+      - "-//test/proto/..."
+      - "-//tools/rust_analyzer/..."
+      - "-//tools/runfiles/..."
+      - "-//test/rustfmt/..."
+      - "@examples//..."
+      - "-@examples//ffi/rust_calling_c:matrix_dylib_test"
+      - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked"
+      - "-@examples//ffi/rust_calling_c/simple/..."
+      - "-@examples//hello_sys/..."
+      - "-@examples//complex_sys/..."
+      - "-@examples//proto/..."
+      - "-@examples//wasm/..."
     build_targets: *windows_targets
     test_targets: *windows_targets
   examples:
     name: Examples
     platform: ubuntu1804
     working_directory: examples
     test_targets:
-    - //...
+      - //...
   docs_linux:
     name: Docs
     platform: ubuntu1804
     working_directory: docs
     build_targets:
-    - //...
-  docs_macos:
-    name: Docs
-    platform: macos
-    working_directory: docs
-    build_targets:
-    - //...
+      - //...
+    run_targets:
+      - "//:test_docs"
   clippy_examples:
     name: Clippy on Examples
     platform: ubuntu1804
     working_directory: examples
     build_flags:
-    - "--aspects=@rules_rust//rust:rust.bzl%rust_clippy_aspect"
-    - "--output_groups=clippy_checks"
+      - "--aspects=@rules_rust//rust:rust.bzl%rust_clippy_aspect"
+      - "--output_groups=clippy_checks"
     build_targets:
-    - //...
+      - //...
   clippy_failure:
     name: Negative Clippy Tests
     platform: ubuntu1804
     shell_commands:
-    - ./test/clippy/clippy_failure_test.sh
+      - ./test/clippy/clippy_failure_test.sh
   ubuntu2004_clang:
     name: Ubuntu 20.04 with Clang
     platform: ubuntu2004

diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,6 @@
 # vscode
 .vscode
 *.code-workspace
+
+# BazelCI
+bazelci.py
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -119,3 +119,13 @@ stardoc(
     symbol_names = [symbol for k in PAGES.keys() for symbol in PAGES[k]],
     deps = [":all_docs"],
 )
+
+sh_binary(
+    name = "update_docs",
+    srcs = ["update_docs.sh"],
+)
+
+sh_binary(
+    name = "test_docs",
+    srcs = ["test_docs.sh"],
+)
diff --git a/docs/cargo_build_script.md b/docs/cargo_build_script.md
@@ -6,7 +6,7 @@
 ## cargo_build_script
 
 <pre>
-cargo_build_script(<a href="#cargo_build_script-name">name</a>, <a href="#cargo_build_script-crate_name">crate_name</a>, <a href="#cargo_build_script-crate_features">crate_features</a>, <a href="#cargo_build_script-version">version</a>, <a href="#cargo_build_script-deps">deps</a>, <a href="#cargo_build_script-build_script_env">build_script_env</a>, <a href="#cargo_build_script-data">data</a>, <a href="#cargo_build_script-links">links</a>,
+cargo_build_script(<a href="#cargo_build_script-name">name</a>, <a href="#cargo_build_script-crate_features">crate_features</a>, <a href="#cargo_build_script-version">version</a>, <a href="#cargo_build_script-deps">deps</a>, <a href="#cargo_build_script-build_script_env">build_script_env</a>, <a href="#cargo_build_script-data">data</a>, <a href="#cargo_build_script-links">links</a>, <a href="#cargo_build_script-rustc_env">rustc_env</a>,
                    <a href="#cargo_build_script-kwargs">kwargs</a>)
 </pre>
 
@@ -73,14 +73,14 @@ 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 target name for the underlying rule   |  none |
-| <a id="cargo_build_script-crate_name"></a>crate_name |  Name of the crate associated with this build script target.   |  <code>""</code> |
+| <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 _build_script.   |  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 defined by <code>crate_name</code>.   |  <code>[]</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 or tools 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-kwargs"></a>kwargs |  Forwards to the underlying <code>rust_binary</code> rule.   |  none |