Add Bazel support to the documentation

docs/Readme.md

@@ -29,7 +29,7 @@ Once you're up and running consider the following reference material.
 * [Frequently Asked Questions (FAQ)](faq.md#top)
 * [Best practices and other tips](usage-tips.md#top)
 * [CMake integration](cmake-integration.md#top)
-* [CI and other miscellaneous pieces](ci-and-misc.md#top)
+* [Tooling integration (CI, test runners, other)](ci-and-misc.md#top)
 * [Known limitations](limitations.md#top)
 
 **Other:**

docs/ci-and-misc.md

@@ -1,8 +1,15 @@
 <a id="top"></a>
-# CI and other odd pieces
+# Tooling integration (CI, test runners and so on)
+
+**Contents**<br>
+[Continuous Integration systems](#continuous-integration-systems)<br>
+[Bazel test runner integration](#bazel-test-runner-integration)<br>
+[Low-level tools](#low-level-tools)<br>
+[CMake](#cmake)<br>
+
+This page talks about Catch2's integration with other related tooling,
+like Continuous Integration and 3rd party test runners.
 
-This page talks about how Catch integrates with Continuous Integration
-Build Systems may refer to low-level tools, like CMake, or larger systems that run on servers, like Jenkins or TeamCity. This page will talk about both.
 
 ## Continuous Integration systems
 
@@ -51,6 +58,26 @@ Because of the incremental nature of Catch's test suites and ability to run spec
 [SonarQube Generic Test Data](https://docs.sonarqube.org/latest/analysis/generic-test/) XML format for tests metrics.
 
 
+## Bazel test runner integration
+
+Catch2 understands some of the environment variables Bazel uses to control
+test execution. Specifically it understands
+
+ * JUnit output path via `XML_OUTPUT_FILE`
+ * Test filtering via `TESTBRIDGE_TEST_ONLY`
+ * Test sharding via `TEST_SHARD_INDEX`, `TEST_TOTAL_SHARDS`, and `TEST_SHARD_STATUS_FILE`
+
+> Support for `XML_OUTPUT_FILE` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 3.0.1
+
+> Support for `TESTBRIDGE_TEST_ONLY` and sharding was introduced in Catch2 X.Y.Z
+
+This integration is enabled via either a [compile time configuration
+option](configuration.md#bazel-support), or via `BAZEL_TEST` environment
+variable set to "1".
+
+> Support for `BAZEL_TEST` was [introduced](https://github.com/catchorg/Catch2/pull/2459) in Catch2 3.1.0
+
+
 ## Low-level tools
 
 ### CodeCoverage module (GCOV, LCOV...)

docs/configuration.md

@@ -98,13 +98,19 @@ is equivalent with the out-of-the-box experience.
 
 
 ## Bazel support
-When `CATCH_CONFIG_BAZEL_SUPPORT` is defined or when `BAZEL_TEST=1` (which is set by the Bazel inside of a test environment),
+
-Catch2 will register a `JUnit` reporter writing to a path pointed by `XML_OUTPUT_FILE` provided by Bazel.
+Compiling Catch2 with `CATCH_CONFIG_BAZEL_SUPPORT` force-enables Catch2's
+support for Bazel's environment variables (normally Catch2 looks for
+`BAZEL_TEST=1` env var first).
+
+This can be useful if you are using older versions of Bazel, that do not
+yet have `BAZEL_TEST` env var support.
 
 > `CATCH_CONFIG_BAZEL_SUPPORT` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 3.0.1.
 
 > `CATCH_CONFIG_BAZEL_SUPPORT` was [deprecated](https://github.com/catchorg/Catch2/pull/2459) in Catch2 3.1.0.
 
+
 ## C++11 toggles
 
     CATCH_CONFIG_CPP11_TO_STRING // Use `std::to_string`