From c6352c3e1f63725ca39e48ee3fd79e47e5ecae76 Mon Sep 17 00:00:00 2001
From: Clare Macrae <github@cfmacrae.fastmail.co.uk>
Date: Fri, 23 Oct 2020 19:47:05 +0100
Subject: [PATCH] Embed the script buildAndTest.sh inside the docs

---
 docs/contributing.md          | 39 +++++++++++++++++++++--------------
 tools/scripts/buildAndTest.sh |  2 ++
 2 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/docs/contributing.md b/docs/contributing.md
index 020dbfca..1d3143fb 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -78,23 +78,30 @@ the invocation of CMake configuration step.
 Bringing this all together, the steps below should configure, build,
 and run all tests in the `Debug` compilation.
 
-1. Regenerate the amalgamated distribution
+<!-- snippet: catch2-build-and-test -->
+<a id='snippet-catch2-build-and-test'></a>
+```sh
+# 1. Regenerate the amalgamated distribution
+./tools/scripts/generateAmalgamatedFiles.py
+
+# 2. Configure the full test build
+cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug -DCATCH_BUILD_EXAMPLES=ON -DCATCH_BUILD_EXTRA_TESTS=ON
+
+# 3. Run the actual build
+cmake --build debug-build
+
+# 4. Run the tests using CTest
+cd debug-build
+ctest -j 4 --output-on-failure -C Debug
 ```
-$ cd Catch2
-$ ./tools/scripts/generateAmalgamatedFiles.py
-```
-2. Configure the full test build
-```
-$ cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug -DCATCH_BUILD_EXAMPLES=ON -DCATCH_BUILD_EXTRA_TESTS=ON
-```
-3. Run the actual build
-```
-$ cmake --build debug-build
-```
-4. Run the tests using CTest
-```
-$ cd debug-build
-$ ctest -j 4 --output-on-failure -C Debug
+<sup><a href='/tools/scripts/buildAndTest.sh#L6-L19' title='File snippet `catch2-build-and-test` was extracted from'>snippet source</a> | <a href='#snippet-catch2-build-and-test' title='Navigate to start of snippet `catch2-build-and-test`'>anchor</a></sup>
+<!-- endSnippet -->
+
+For convenience, the above commands are in the script `tools/scripts/buildAndTest.sh`, and can be run like this:
+
+```bash
+cd Catch2
+./tools/scripts/buildAndTest.sh
 ```
 
 If you added new tests, you will likely see `ApprovalTests` failure.
diff --git a/tools/scripts/buildAndTest.sh b/tools/scripts/buildAndTest.sh
index 42a7f6e1..d5bca96d 100755
--- a/tools/scripts/buildAndTest.sh
+++ b/tools/scripts/buildAndTest.sh
@@ -3,6 +3,7 @@
 # Start at the root of the Catch project directory, for example:
 # cd Catch2
 
+# begin-snippet: catch2-build-and-test
 # 1. Regenerate the amalgamated distribution
 ./tools/scripts/generateAmalgamatedFiles.py
 
@@ -15,3 +16,4 @@ cmake --build debug-build
 # 4. Run the tests using CTest
 cd debug-build
 ctest -j 4 --output-on-failure -C Debug
+# end-snippet