Reorganise Documentation Site (#2444)

* Tidy docs

* Move to new structure

* Remove sidebar header info

* Edits

* Info blocks

* Remove duplicate sentences

* Tidy

* Fix

* Update locations

* Update sidebars

* Fix

* Fix config

* Fix link

* Missing files

* Bring back removed files

* Assertions section

* Fix

* Fix

Author: thomhurst

docs/README.md

@@ -39,3 +39,4 @@ $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+

docs/docs/tutorial-assertions/and-conditions.md renamed to docs/docs/assertions/and-conditions.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Awaiting
 
 In TUnit you `await` your assertions, and this serves two purposes:
@@ -10,7 +6,8 @@ In TUnit you `await` your assertions, and this serves two purposes:
 
 Because of this, your tests should be `async` and return a `Task`.
 
-Don't worry about forgetting to `await` - There's an analyzer built in that will notify you if you've missed any!
+Don't worry about forgetting to `await` - There's an analyzer built in that will notify you if you've missed any!  
+If you forget to `await`, your assertion will not actually be executed, and your test may pass when it should fail.
 
 This will error:
 
@@ -37,4 +34,4 @@ This won't:
 ```
 
 TUnit is able to take in asynchronous delegates. To be able to assert on these, we need to execute the code. We want to avoid sync-over-async, as this can cause problems and block the thread pool, slowing down your test suite.
-And with how fast .NET has become, the overhead of `Task`s and `async` methods shouldn't be noticable.
+And with how fast .NET has become, the overhead of `Task`s and `async` methods shouldn't be noticable.

docs/docs/tutorial-assertions/assertion-groups.md renamed to docs/docs/assertions/assertion-groups.md

@@ -38,4 +38,4 @@ TUnit can execute your delegates for you, and this allows you to assert on the d
             return Task.CompletedTask;
         });
     }
-```
+```

docs/docs/tutorial-assertions/awaiting.md renamed to docs/docs/assertions/awaiting.md

@@ -107,4 +107,4 @@ public class StringEqualsExpectedValueAssertCondition(string expected, StringCom
                 $"found \"{actualValue}\"");
     }
 }
-```
+```

docs/docs/tutorial-assertions/delegates.md renamed to docs/docs/assertions/delegates.md

@@ -1,16 +1,15 @@
----
-sidebar_position: 2
----
-
 # Chaining and Converting
 
-We may want to chain assertions together that change the type of object being asserted, to keep the assertions reading clear and concise, and not having to declare more variables and more boiler-plate assert calls.
+TUnit allows you to chain assertions that change the type being asserted, enabling fluent and expressive test code.  
+This is useful when an assertion transforms the value (e.g., parsing a response), and you want to continue asserting on the new type.
 
-This is possible in TUnit.
+Chaining is especially helpful when you want to perform multiple assertions on a value that is transformed by a previous assertion, without having to create intermediate variables.
 
 For example:
 
 ```csharp
+        HttpResponseMessage response = ...;
+        
         await Assert.That(response)
             .IsProblemDetails()
             .And
@@ -86,4 +85,4 @@ public static class ProblemDetailsAssertionExtensions
         return valueSource.RegisterAssertion(new ProblemDetailsHasDetailAssertCondition(detail), [detailExpression]);
     }
 }
-```
+```

docs/docs/tutorial-assertions/extensibility/custom-assertions.md renamed to docs/docs/assertions/extensibility/custom-assertions.md

@@ -1,9 +1,10 @@
----
-sidebar_position: 3
----
-
 # Returning Data via `await`
 
+Sometimes, you may want your assertion to return a value, such as an item found in a collection, so you can use it in further assertions or logic.  
+TUnit supports this by allowing your assertion to return a mapped result when awaited.
+
+This is useful for scenarios where you want to extract a value from an assertion and use it in subsequent test logic, reducing the need for manual extraction or casting.
+
 It may make sense for our assertions to return data that is different from the input, based on what the assertion is doing. This can allow more cleanly written tests than have to manually do casting or parsing afterwards.
 
 For example, `await Assert.That(collection).Contains(item => item.Price < 0.99)`
@@ -84,4 +85,4 @@ public static MappableResultAssertionBuilder<IEnumerable<TInner>, EnumerableCont
             (_, assertCondition) => assertCondition.FoundItem
         );
     }
-```
+```

docs/docs/tutorial-assertions/extensibility/chaining-and-converting.md renamed to docs/docs/assertions/extensibility/extensibility-chaining-and-converting.md

@@ -24,4 +24,4 @@ When using this, only one condition needs to pass:
             .Or.IsEqualTo(3)
             .Or.IsEqualTo(4);
     }
-```
+```