Added test for ensuring docs are always appropriately updated (#576)

* Added test for ensuring docs are always appropriately updated

* Updated docs

.bazelci/config.yaml

@@ -138,6 +138,8 @@ tasks:
     working_directory: docs
     build_targets:
       - //...
+    run_targets:
+      - //:test_docs
   min_supported_version:
     name: "Minimum Supported Version"
     bazel: "3.7.0"

.gitignore

@@ -71,6 +71,9 @@ fabric.properties
 # Vim swap files
 .*.sw?
 
+# Bazel CI
+bazelci.py
+
 #####
 # Bazel: https://github.com/github/gitignore/blob/master/community/Bazel.gitignore
 #####

README.md

@@ -25,11 +25,11 @@ For more generalized updates, please see [NEWS.md](./NEWS.md) or checkout the
 
 ## Building CMake projects
 
-- Build libraries/binaries with CMake from sources using cmake_external rule
-- Use cmake_external targets in [cc_library][ccl], [cc_binary][ccb] targets as dependency
-- Bazel [cc_toolchain][cct] parameters are used inside cmake_external build
-- See full list of cmake_external arguments below 'example'
-- cmake_external is defined in `./tools/build_defs`
+- Build libraries/binaries with CMake from sources using cmake rule
+- Use cmake targets in [cc_library][ccl], [cc_binary][ccb] targets as dependency
+- Bazel [cc_toolchain][cct] parameters are used inside cmake build
+- See full list of cmake arguments below 'example'
+- cmake is defined in `./tools/build_defs`
 - Works on Ubuntu, Mac OS and Windows(\* see special notes below in Windows section) operating systems
 
 **Example:**
@@ -38,7 +38,7 @@ For more generalized updates, please see [NEWS.md](./NEWS.md) or checkout the
 The example for **Windows** is below, in the section 'Usage on Windows'.
 
 - In `WORKSPACE.bazel`, we use a `http_archive` to download tarballs with the libraries we use.
-- In `BUILD.bazel`, we instantiate a `cmake_external` rule which behaves similarly to a [cc_library][ccl], which can then be used in a C++ rule ([cc_binary][ccb] in this case).
+- In `BUILD.bazel`, we instantiate a `cmake` rule which behaves similarly to a [cc_library][ccl], which can then be used in a C++ rule ([cc_binary][ccb] in this case).
 
 In `WORKSPACE.bazel`, put
 
@@ -105,7 +105,7 @@ bazel build //:pcre
 
 **Usage on Windows**
 
-When using on Windows, you should start Bazel in MSYS2 shell, as the shell script inside cmake_external assumes this.
+When using on Windows, you should start Bazel in MSYS2 shell, as the shell script inside cmake assumes this.
 Also, you should explicitly specify **make commands and option to generate CMake crosstool file**.
 
 The default generator for CMake will be detected automatically, or you can specify it explicitly.

docs/BUILD.bazel

@@ -34,8 +34,9 @@ genrule(
     outs = ["generate_docs.sh"],
     cmd = """cat << EOF > $@
 #!/bin/bash
-set -e
+set -euo pipefail
 cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/README.md
+EOF
 """,
 )
 
@@ -44,3 +45,8 @@ sh_binary(
     srcs = [":generate_docs_src"],
     data = [":docs"],
 )
+
+sh_binary(
+    name = "test_docs",
+    srcs = ["test_docs.sh"]
+)

docs/README.md

@@ -42,7 +42,7 @@ Rule for building Boost. Invokes bootstrap.sh and then b2 install.
 | <a id="boost_build-data"></a>data |  Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="boost_build-defines"></a>defines |  Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options.   | List of strings | optional | [] |
 | <a id="boost_build-deps"></a>deps |  Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule)   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="boost_build-env"></a>env |  Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
+| <a id="boost_build-env"></a>env |  Environment variables to set during the build. <code>$(execpath)</code> macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="boost_build-headers_only"></a>headers_only |  __deprecated__: Use <code>out_headers_only</code> instead.   | Boolean | optional | False |
 | <a id="boost_build-interface_libraries"></a>interface_libraries |  __deprecated__: Use <code>out_interface_libs</code> instead.   | List of strings | optional | [] |
 | <a id="boost_build-lib_name"></a>lib_name |  Library name. Defines the name of the install directory and the name of the static library, if no output files parameters are defined (any of static_libraries, shared_libraries, interface_libraries, binaries_names) Optional. If not defined, defaults to the target's name.   | String | optional | "" |
@@ -94,7 +94,7 @@ Rule for building external library with CMake.
 | <a id="cmake-data"></a>data |  Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="cmake-defines"></a>defines |  Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options.   | List of strings | optional | [] |
 | <a id="cmake-deps"></a>deps |  Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule)   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="cmake-env"></a>env |  Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
+| <a id="cmake-env"></a>env |  Environment variables to set during the build. <code>$(execpath)</code> macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="cmake-env_vars"></a>env_vars |  CMake environment variable values to join with toolchain-defined. For example, additional <code>CXXFLAGS</code>.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="cmake-generate_args"></a>generate_args |  Arguments for CMake's generate command. Arguments should be passed as key/value pairs. eg: <code>["-G Ninja", "--debug-output", "-DFOO=bar"]</code>. Note that unless a generator (<code>-G</code>) argument is provided, the default generators are [Unix Makefiles](https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html) for Linux and MacOS and [Ninja](https://cmake.org/cmake/help/latest/generator/Ninja.html) for Windows.   | List of strings | optional | [] |
 | <a id="cmake-generate_crosstool_file"></a>generate_crosstool_file |  When True, CMake crosstool file will be generated from the toolchain values, provided cache-entries and env_vars (some values will still be passed as <code>-Dkey=value</code> and environment variables). If <code>CMAKE_TOOLCHAIN_FILE</code> cache entry is passed, specified crosstool file will be used When using this option to cross-compile, it is required to specify <code>CMAKE_SYSTEM_NAME</code> in the cache_entries   | Boolean | optional | True |
@@ -187,14 +187,14 @@ Rule for building external libraries with configure-make pattern. Some 'configur
 | <a id="configure_make-data"></a>data |  Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="configure_make-defines"></a>defines |  Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options.   | List of strings | optional | [] |
 | <a id="configure_make-deps"></a>deps |  Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule)   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="configure_make-env"></a>env |  Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
+| <a id="configure_make-env"></a>env |  Environment variables to set during the build. <code>$(execpath)</code> macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="configure_make-headers_only"></a>headers_only |  __deprecated__: Use <code>out_headers_only</code> instead.   | Boolean | optional | False |
 | <a id="configure_make-install_prefix"></a>install_prefix |  Install prefix, i.e. relative path to where to install the result of the build. Passed to the 'configure' script with --prefix flag.   | String | optional | "" |
 | <a id="configure_make-interface_libraries"></a>interface_libraries |  __deprecated__: Use <code>out_interface_libs</code> instead.   | List of strings | optional | [] |
 | <a id="configure_make-lib_name"></a>lib_name |  Library name. Defines the name of the install directory and the name of the static library, if no output files parameters are defined (any of static_libraries, shared_libraries, interface_libraries, binaries_names) Optional. If not defined, defaults to the target's name.   | String | optional | "" |
 | <a id="configure_make-lib_source"></a>lib_source |  Label with source code to build. Typically a filegroup for the source of remote repository. Mandatory.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required |  |
 | <a id="configure_make-linkopts"></a>linkopts |  Optional link options to be passed up to the dependencies of this library   | List of strings | optional | [] |
-| <a id="configure_make-make_commands"></a>make_commands |  Optinal make commands, defaults to ["make", "make install"]   | List of strings | optional | ["make", "make install"] |
+| <a id="configure_make-make_commands"></a>make_commands |  Optional make commands.   | List of strings | optional | ["make", "make install"] |
 | <a id="configure_make-out_bin_dir"></a>out_bin_dir |  Optional name of the output subdirectory with the binary files, defaults to 'bin'.   | String | optional | "bin" |
 | <a id="configure_make-out_binaries"></a>out_binaries |  Optional names of the resulting binaries.   | List of strings | optional | [] |
 | <a id="configure_make-out_headers_only"></a>out_headers_only |  Flag variable to indicate that the library produces only headers   | Boolean | optional | False |
@@ -238,7 +238,7 @@ Rule for building external libraries with GNU Make. GNU Make commands (make and
 | <a id="make-data"></a>data |  Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="make-defines"></a>defines |  Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options.   | List of strings | optional | [] |
 | <a id="make-deps"></a>deps |  Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule)   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="make-env"></a>env |  Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
+| <a id="make-env"></a>env |  Environment variables to set during the build. <code>$(execpath)</code> macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="make-headers_only"></a>headers_only |  __deprecated__: Use <code>out_headers_only</code> instead.   | Boolean | optional | False |
 | <a id="make-interface_libraries"></a>interface_libraries |  __deprecated__: Use <code>out_interface_libs</code> instead.   | List of strings | optional | [] |
 | <a id="make-keep_going"></a>keep_going |  __deprecated__: To maintain this behavior, pass <code>-k</code> to the <code>args</code> attribute when not using the <code>make_commands</code> attribute.   | Boolean | optional | True |
@@ -331,7 +331,7 @@ Rule for building external libraries with [Ninja](https://ninja-build.org/).
 | <a id="ninja-defines"></a>defines |  Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options.   | List of strings | optional | [] |
 | <a id="ninja-deps"></a>deps |  Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule)   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="ninja-directory"></a>directory |  A directory to pass as the <code>-C</code> argument. The rule will always use the root directory of the <code>lib_sources</code> attribute if this attribute is not set   | String | optional | "" |
-| <a id="ninja-env"></a>env |  Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
+| <a id="ninja-env"></a>env |  Environment variables to set during the build. <code>$(execpath)</code> macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="ninja-headers_only"></a>headers_only |  __deprecated__: Use <code>out_headers_only</code> instead.   | Boolean | optional | False |
 | <a id="ninja-interface_libraries"></a>interface_libraries |  __deprecated__: Use <code>out_interface_libs</code> instead.   | List of strings | optional | [] |
 | <a id="ninja-lib_name"></a>lib_name |  Library name. Defines the name of the install directory and the name of the static library, if no output files parameters are defined (any of static_libraries, shared_libraries, interface_libraries, binaries_names) Optional. If not defined, defaults to the target's name.   | String | optional | "" |

docs/test_docs.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+set -euo pipefail
+
+pushd "${BUILD_WORKSPACE_DIRECTORY}" &> /dev/null
+bazel run //:generate_docs
+if [ -n "$(git status --porcelain)" ]; then 
+    git status
+    echo '/docs is out of date. Please run `bazel run //:generate_docs` from that directory and commit the results' >&2
+    exit 1
+fi
+popd &> /dev/null

foreign_cc/private/framework.bzl

@@ -95,7 +95,7 @@ CC_EXTERNAL_RULE_ATTRIBUTES = {
     "env": attr.string_dict(
         doc = (
             "Environment variables to set during the build. " +
-            "$(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, " +
+            "`$(execpath)` macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, " +
             "but unlike with other rules, these will be replaced with absolute paths to those files, " +
             "because the build does not run in the exec root. " +
             "No other macros are supported."
@@ -133,7 +133,7 @@ CC_EXTERNAL_RULE_ATTRIBUTES = {
         default = [],
     ),
     "make_commands": attr.string_list(
-        doc = "Optinal make commands, defaults to [\"make\", \"make install\"]",
+        doc = "Optional make commands.",
         mandatory = False,
         default = ["make", "make install"],
     ),