catchorg · nrbnlulu · Apr 16, 2023 · Apr 16, 2023 · May 29, 2023 · May 29, 2023
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,31 @@
+name: 📖 docs
+
+on:
+  push:
+    branches: [devel]
+  pull_request:
+    branches: [devel]
+
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - name: Install Poetry
+      uses: abatilo/actions-poetry@v2
+
+    - name: Install dependencies
+      run: poetry install
+
+    - name: build docs
+      run: poetry run mkdocs build
+
+    - name: deploy
+      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/devel' }}
+      run: poetry run mkdocs gh-deploy --force
+
diff --git a/docs/Readme.md b/docs/Readme.md
@@ -4,40 +4,45 @@
 To get the most out of Catch2, start with the [tutorial](tutorial.md#top).
 Once you're up and running consider the following reference material.
 
-**Writing tests:**
-* [Assertion macros](assertions.md#top)
-* [Matchers (asserting complex properties)](matchers.md#top)
-* [Comparing floating point numbers](comparing-floating-point-numbers.md#top)
-* [Logging macros](logging.md#top)
-* [Test cases and sections](test-cases-and-sections.md#top)
-* [Test fixtures](test-fixtures.md#top)
-* [Explicitly skipping, passing, and failing tests at runtime](skipping-passing-failing.md#top)
-* [Reporters (output customization)](reporters.md#top)
-* [Event Listeners](event-listeners.md#top)
-* [Data Generators (value parameterized tests)](generators.md#top)
-* [Other macros](other-macros.md#top)
-* [Micro benchmarking](benchmarks.md#top)
-
-**Fine tuning:**
-* [Supplying your own main()](own-main.md#top)
-* [Compile-time configuration](configuration.md#top)
-* [String Conversions](tostring.md#top)
-
-**Running:**
-* [Command line](command-line.md#top)
-
-**Odds and ends:**
-* [Frequently Asked Questions (FAQ)](faq.md#top)
-* [Best practices and other tips](usage-tips.md#top)
-* [CMake integration](cmake-integration.md#top)
-* [Tooling integration (CI, test runners, other)](ci-and-misc.md#top)
-* [Known limitations](limitations.md#top)
-
-**Other:**
-* [Why Catch2?](why-catch.md#top)
-* [Migrating from v2 to v3](migrate-v2-to-v3.md#top)
-* [Open Source Projects using Catch2](opensource-users.md#top)
-* [Commercial Projects using Catch2](commercial-users.md#top)
-* [Contributing](contributing.md#top)
-* [Release Notes](release-notes.md#top)
-* [Deprecations and incoming changes](deprecations.md#top)
+**Writing tests:**  
+
+- [Assertion macros](assertions.md#top)
+- [Matchers (asserting complex properties)](matchers.md#top)
+- [Comparing floating point numbers](comparing-floating-point-numbers.md#top)
+- [Logging macros](logging.md#top)
+- [Test cases and sections](test-cases-and-sections.md#top)
+- [Test fixtures](test-fixtures.md#top)
+- [Explicitly skipping, passing, and failing tests at runtime](skipping-passing-failing.md#top)
+- [Reporters (output customization)](reporters.md#top)
+- [Event Listeners](event-listeners.md#top)
+- [Data Generators (value parameterized tests)](generators.md#top)
+- [Other macros](other-macros.md#top)
+- [Micro benchmarking](benchmarks.md#top)
+
+**Fine tuning:**  
+
+- [Supplying your own main()](own-main.md#top)
+- [Compile-time configuration](configuration.md#top)
+- [String Conversions](tostring.md#top)
+
+**Running:**  
+
+- [Command line](command-line.md#top)
+
+**Odds and ends:**  
+
+- [Frequently Asked Questions (FAQ)](faq.md#top)
+- [Best practices and other tips](usage-tips.md#top)
+- [CMake integration](cmake-integration.md#top)
+- [Tooling integration (CI, test runners, other)](ci-and-misc.md#top)
+- [Known limitations](limitations.md#top)
+
+**Other:**  
+
+- [Why Catch2?](why-catch.md#top)
+- [Migrating from v2 to v3](migrate-v2-to-v3.md#top)
+- [Open Source Projects using Catch2](opensource-users.md#top)
+- [Commercial Projects using Catch2](commercial-users.md#top)
+- [Contributing](contributing.md#top)
+- [Release Notes](release-notes.md#top)
+- [Deprecations and incoming changes](deprecations.md#top)
diff --git a/docs/assertions.md b/docs/assertions.md
@@ -26,7 +26,7 @@ The ```CHECK``` family are equivalent but execution continues in the same test c
 Evaluates the expression and records the result. If an exception is thrown, it is caught, reported, and counted as a failure. These are the macros you will use most of the time.
 
 Examples:
-```
+```cpp
 CHECK( str == "string value" );
 CHECK( thisReturnsTrue() );
 REQUIRE( i == 42 );
@@ -177,6 +177,4 @@ TEST_CASE_METHOD((Fixture<int, int>), "foo", "[bar]") {
 This solution is not always applicable, because it might require extra
 changes on the Catch's side to work.
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/ci-and-misc.md b/docs/ci-and-misc.md
@@ -105,6 +105,4 @@ when stepping through code.
 integration with CMake has been moved to its own page.](cmake-integration.md#top)
 
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/cmake-integration.md b/docs/cmake-integration.md
@@ -408,6 +408,4 @@ cd vcpkg
 The catch2 port in vcpkg is kept up to date by microsoft team members and community contributors.
 If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/command-line.md b/docs/command-line.md
@@ -583,6 +583,4 @@ ignored.
 Verbosity defaults to _normal_.
 
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/commercial-users.md b/docs/commercial-users.md
@@ -18,6 +18,4 @@ with you sharing this fact.
  - [King](https://king.com)
 
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/comparing-floating-point-numbers.md b/docs/comparing-floating-point-numbers.md
@@ -187,6 +187,4 @@ to Approx's value when computing the allowed relative margin from the
 Approx's value.
 
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -265,31 +265,4 @@ The macro will be used as is, that is, `CATCH_BREAK_INTO_DEBUGGER();`
 must compile and must break into debugger.
 
 
-## Static analysis support
 
-> Introduced in Catch2 X.Y.Z.
-
-Some parts of Catch2, e.g. `SECTION`s, can be hard for static analysis
-tools to reason about. Catch2 can change its internals to help static
-analysis tools reason about the tests.
-
-Catch2 automatically detects some static analysis tools (initial
-implementation checks for clang-tidy and Coverity), but you can override
-its detection (in either direction) via
-
-```
-CATCH_CONFIG_EXPERIMENTAL_STATIC_ANALYSIS_SUPPORT     // force enables static analysis help
-CATCH_CONFIG_NO_EXPERIMENTAL_STATIC_ANALYSIS_SUPPORT  // force disables static analysis help
-```
-
-_As the name suggests, this is currently experimental, and thus we provide
-no backwards compatibility guarantees._
-
-**DO NOT ENABLE THIS FOR BUILDS YOU INTEND TO RUN.** The changed internals
-are not meant to be runnable, only "scannable".
-
-
-
----
-
-[Home](Readme.md#top)
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -135,6 +135,20 @@ other people can use it as well. This section collects some technical
 information that you will need for updating Catch2's documentation, and
 possibly some generic advise as well.
 
+We use mkdocs for documentation and poetry for python environment.
+first install poetry (you'll need python...)
+```console
+pip install poetry
+```
+Poetry will install our docs dependencies
+```console
+poetry install
+```
+serve the docs locally to see your changes
+```console
+poetry run mkdocs serve
+```
+
 
 ### Technicalities
 
@@ -152,9 +166,7 @@ should use. It provides you with the top anchor mentioned to link to
 Text that explains how to use the cool feature.
 
 
----
 
-[Home](Readme.md#top)
 ```
 
 * Crosslinks to different pages should target the `top` anchor, like this
@@ -338,6 +350,4 @@ while contributing to Catch2.
 _This documentation will always be in-progress as new information comes
 up, but we are trying to keep it as up to date as possible._
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/deprecations.md b/docs/deprecations.md
@@ -35,6 +35,4 @@ being aborted (when using `--abort` or `--abortx`). It is however
 **NOT** invoked for test cases that are [explicitly skipped using the `SKIP`
 macro](skipping-passing-failing.md#top).
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/event-listeners.md b/docs/event-listeners.md
@@ -39,6 +39,4 @@ _Note that you should not use any assertion macros within a Listener!_
 own page](reporter-events.md#top).
 
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/faq.md b/docs/faq.md
@@ -89,6 +89,4 @@ above what your platform does. **Important: `<random>`'s distributions
 are not specified to be repeatable across different platforms.**
 
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/list-of-examples.md b/docs/list-of-examples.md
@@ -3,44 +3,86 @@
 
 ## Already available
 
-- Test Case: [Single-file](../examples/010-TestCase.cpp)
-- Test Case: [Multiple-file 1](../examples/020-TestCase-1.cpp), [2](../examples/020-TestCase-2.cpp)
-- Assertion: [REQUIRE, CHECK](../examples/030-Asn-Require-Check.cpp)
-- Fixture: [Sections](../examples/100-Fix-Section.cpp)
-- Fixture: [Class-based fixtures](../examples/110-Fix-ClassFixture.cpp)
-- BDD: [SCENARIO, GIVEN, WHEN, THEN](../examples/120-Bdd-ScenarioGivenWhenThen.cpp)
-- Listener: [Listeners](../examples/210-Evt-EventListeners.cpp)
-- Configuration: [Provide your own output streams](../examples/231-Cfg-OutputStreams.cpp)
-- Generators: [Create your own generator](../examples/300-Gen-OwnGenerator.cpp)
-- Generators: [Use map to convert types in GENERATE expression](../examples/301-Gen-MapTypeConversion.cpp)
-- Generators: [Run test with a table of input values](../examples/302-Gen-Table.cpp)
-- Generators: [Use variables in generator expressions](../examples/310-Gen-VariablesInGenerators.cpp)
-- Generators: [Use custom variable capture in generator expressions](../examples/311-Gen-CustomCapture.cpp)
+### Test Case: Single-file
+```cpp
+--8<-- "examples/010-TestCase.cpp"
+```
+### Test Case: Multiple-files
+=== "File 1"
+    ```cpp
+    --8<-- "examples/020-TestCase-1.cpp"
+    ```
+=== "File 2"
+    ```cpp
+    --8<-- "examples/020-TestCase-2.cpp"
+    ```
+### Assertion (REQUIRE, CHECK)
+```cpp
+--8<-- "examples/030-Asn-Require-Check.cpp"
+```
+### Fixtures 
+#### Sections
+```cpp
+--8<-- "examples/100-Fix-Section.cpp"
+```
+#### Class-based fixtures
+```cpp
+--8<-- "examples/110-Fix-ClassFixture.cpp"
+```
+### BDD (SCENARIO, GIVEN, WHEN, THEN)
+```cpp
+--8<-- "examples/120-Bdd-ScenarioGivenWhenThen.cpp"
+```
+### Listener
+```cpp
+--8<-- "examples/210-Evt-EventListeners.cpp"
+```
+### Configuration - *Provide your own output streams*
+```cpp
+--8<-- "examples/231-Cfg-OutputStreams.cpp"
+```
+### Generators
+#### Create your own generator
+```cpp
+--8<-- "examples/300-Gen-OwnGenerator.cpp"
+```
+#### Use map to convert types in GENERATE expression
+```cpp
+--8<-- "examples/301-Gen-MapTypeConversion.cpp"
+```
+#### Run test with a table of input values
+```cpp
+--8<-- "examples/302-Gen-Table.cpp"
+```
+#### Use variables in generator expressions
+```cpp
+--8<-- "examples/310-Gen-VariablesInGenerators.cpp"
+```
+#### Use custom variable capture in generator expressions
+```cpp
+--8<-- "examples/311-Gen-CustomCapture.cpp"
+```
 
+??? note "Planned (TBD)"
+
+      - Assertion: [REQUIRE_THAT and Matchers](../examples/040-Asn-RequireThat.cpp)
+      - Assertion: [REQUIRE_NO_THROW](../examples/050-Asn-RequireNoThrow.cpp)
+      - Assertion: [REQUIRE_THROWS](../examples/050-Asn-RequireThrows.cpp)
+      - Assertion: [REQUIRE_THROWS_AS](../examples/070-Asn-RequireThrowsAs.cpp)
+      - Assertion: [REQUIRE_THROWS_WITH](../examples/080-Asn-RequireThrowsWith.cpp)
+      - Assertion: [REQUIRE_THROWS_MATCHES](../examples/090-Asn-RequireThrowsMatches.cpp)
+      - Floating point: [Approx - Comparisons](../examples/130-Fpt-Approx.cpp)
+      - Logging: [CAPTURE - Capture expression](../examples/140-Log-Capture.cpp)
+      - Logging: [INFO - Provide information with failure](../examples/150-Log-Info.cpp)
+      - Logging: [WARN - Issue warning](../examples/160-Log-Warn.cpp)
+      - Logging: [FAIL, FAIL_CHECK - Issue message and force failure/continue](../examples/170-Log-Fail.cpp)
+      - Logging: [SUCCEED - Issue message and continue](../examples/180-Log-Succeed.cpp)
+      - Report: [User-defined type](../examples/190-Rpt-ReportUserDefinedType.cpp)
+      - Report: [User-defined reporter](../examples/202-Rpt-UserDefinedReporter.cpp)
+      - Report: [Automake reporter](../examples/205-Rpt-AutomakeReporter.cpp)
+      - Report: [TAP reporter](../examples/206-Rpt-TapReporter.cpp)
+      - Report: [Multiple reporter](../examples/208-Rpt-MultipleReporters.cpp)
+      - Configuration: [Provide your own main()](../examples/220-Cfg-OwnMain.cpp)
+      - Configuration: [Compile-time configuration](../examples/230-Cfg-CompileTimeConfiguration.cpp)
+      - Configuration: [Run-time configuration](../examples/240-Cfg-RunTimeConfiguration.cpp)
 
-## Planned
-
-- Assertion: [REQUIRE_THAT and Matchers](../examples/040-Asn-RequireThat.cpp)
-- Assertion: [REQUIRE_NO_THROW](../examples/050-Asn-RequireNoThrow.cpp)
-- Assertion: [REQUIRE_THROWS](../examples/050-Asn-RequireThrows.cpp)
-- Assertion: [REQUIRE_THROWS_AS](../examples/070-Asn-RequireThrowsAs.cpp)
-- Assertion: [REQUIRE_THROWS_WITH](../examples/080-Asn-RequireThrowsWith.cpp)
-- Assertion: [REQUIRE_THROWS_MATCHES](../examples/090-Asn-RequireThrowsMatches.cpp)
-- Floating point: [Approx - Comparisons](../examples/130-Fpt-Approx.cpp)
-- Logging: [CAPTURE - Capture expression](../examples/140-Log-Capture.cpp)
-- Logging: [INFO - Provide information with failure](../examples/150-Log-Info.cpp)
-- Logging: [WARN - Issue warning](../examples/160-Log-Warn.cpp)
-- Logging: [FAIL, FAIL_CHECK - Issue message and force failure/continue](../examples/170-Log-Fail.cpp)
-- Logging: [SUCCEED - Issue message and continue](../examples/180-Log-Succeed.cpp)
-- Report: [User-defined type](../examples/190-Rpt-ReportUserDefinedType.cpp)
-- Report: [User-defined reporter](../examples/202-Rpt-UserDefinedReporter.cpp)
-- Report: [Automake reporter](../examples/205-Rpt-AutomakeReporter.cpp)
-- Report: [TAP reporter](../examples/206-Rpt-TapReporter.cpp)
-- Report: [Multiple reporter](../examples/208-Rpt-MultipleReporters.cpp)
-- Configuration: [Provide your own main()](../examples/220-Cfg-OwnMain.cpp)
-- Configuration: [Compile-time configuration](../examples/230-Cfg-CompileTimeConfiguration.cpp)
-- Configuration: [Run-time configuration](../examples/240-Cfg-RunTimeConfiguration.cpp)
-
----
-
-[Home](Readme.md#top)
diff --git a/docs/logging.md b/docs/logging.md
@@ -154,6 +154,4 @@ to enclose the expression inside parentheses:
 `CAPTURE( (std::pair<int, int>{1, 2}) );`
 
 
----
 
-[Home](Readme.md#top)
diff --git a/docs/matchers.md b/docs/matchers.md
@@ -435,6 +435,4 @@ and new style matchers arbitrarily.
 > `MatcherGenericBase` lives in `catch2/matchers/catch_matchers_templated.hpp`
 
 
----
 
-[Home](Readme.md#top)