doc: reviewed and fix documentation (#39)

Signed-off-by: Frédéric BIDON <fredbi@yahoo.com>

Author: fredbi

docs/doc-site/_index.md

@@ -71,15 +71,15 @@ Import this library in your project like so.
 
     const expected = "expected result"
 
-	result := printImports(input)
-	if result != expected {
-		t.Errorf(
-            "Expected: %s. Got: %s",
-            expected, result, 
-        )
-
-        return
-	}
+	  result := printImports(input)
+	  if result != expected {
+		  t.Errorf(
+        "Expected: %s. Got: %s",
+        expected, result, 
+      )
+
+      return
+	  }
 ```
 {{% /card %}}
 
@@ -94,10 +94,9 @@ Import this library in your project like so.
 
     const expected = "expected result"
 
-	require.Equalf(t,
-        expected, printImports(input),
-        "Expected: %s. Got: %s",
-        expected, result, 
+	  result := printImports(input)
+	  require.Equalf(t, expected, result,
+        "Expected: %s. Got: %s", expected, result, 
     )
 ```
 {{% /card %}}
@@ -169,6 +168,23 @@ See also our [CONTRIBUTING guidelines](./project/contributing/CONTRIBUTING.md).
 
 ---
 
+## See Also
+
+**Getting Started:**
+- [Usage Guide](./usage/USAGE.md) - API conventions and how to navigate the documentation
+- [Tutorial](./usage/TUTORIAL.md) - Best practices and patterns for writing great tests
+- [Examples](./usage/EXAMPLES.md) - Practical code examples for common testing scenarios
+
+**Advanced Topics:**
+- [Generics Guide](./usage/GENERICS.md) - Type-safe assertions with 38 generic functions
+- [Migration Guide](./usage/MIGRATION.md) - Migrating from stretchr/testify v1
+- [Changes from v1](./usage/CHANGES.md) - All changes and improvements in v2
+
+**Reference:**
+- [API Reference](./api/_index.md) - Complete assertion catalog organized by domain
+
+---
+
 {{< children type="card" description="true" >}}
 
 [doc-examples]: ./usage/examples

docs/doc-site/api/_index.md

@@ -53,6 +53,16 @@ Each domain contains assertions regrouped by their use case (e.g. http, json, er
 
 ---
 
+## See Also
+
+- [Usage Guide](../usage/USAGE.md) - API conventions, naming patterns, and how to navigate assertions
+- [Examples](../usage/EXAMPLES.md) - Practical examples showing how to use these assertions
+- [Generics Guide](../usage/GENERICS.md) - Type-safe variants of assertions (marked with {{% icon icon="star" color=orange %}})
+- [Tutorial](../usage/TUTORIAL.md) - Best practices for writing tests with testify
+- [pkg.go.dev](https://pkg.go.dev/github.com/go-openapi/testify/v2) - Full API reference documentation
+
+---
+
 Generated with github.com/go-openapi/testify/codegen/v2
 
 [godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/testify/v2

docs/doc-site/project/README.md

@@ -20,8 +20,8 @@ weight: 1
 > occasions.
 >
 > In this fork, all external stuff is either internalized (`go-spew`, `difflib`),
-> removed (`mocks`, `suite`, `http`) or specifically enabled by importing a specific module
-> (`github.com/go-openapi/testify/v2/enable/yaml`).
+> removed (`mocks`, `suite`, `http`) or specifically enabled by importing this module
+> (`github.com/go-openapi/testify/enable/yaml/v2`).
 
 2. Make it easy to maintain and extend.
 
@@ -74,52 +74,30 @@ while maintaining the flexibility that makes testify useful for real-world testi
 * removed the `suite`, `mocks` and `http` packages
 * replaced internal utility package `_codegen` by `codegen`
 
-### Other (non-breaking) changes
-
-* added `JSONEqBytes`
-* added `YAMLEqBytes`
-* adapted & merged fixes: see [ROADMAP](./maintainers/ROADMAP.md).
-
-## Usage at go-openapi
-
-At this moment, we have identified the following usage in our tools. This API shall remain stable.
-Currently, there are no guarantees about the entry points not in this list.
-
-```
-Condition
-Contains,Containsf
-Empty,Emptyf
-Equal,Equalf
-EqualError,EqualErrorf
-EqualValues,EqualValuesf
-Error,Errorf
-ErrorContains
-ErrorIs
-Fail,Failf
-FailNow
-False,Falsef
-Greater
-Implements
-InDelta,InDeltaf
-IsType,IsTypef
-JSONEq,JSONEqf
-Len,Lenf
-Nil,Nilf
-NoError,NoErrorf
-NotContains,NotContainsf
-NotEmpty,NotEmptyf
-NotEqual
-NotNil,NotNilf
-NotPanics
-NotZeroG
-Panics,PanicsWithValue
-Subset
-True,Truef
-YAMLEq,YAMLEqf
-Zero,Zerof
-```
-
-## [The original README](./maintainers/ORIGINAL.md)
+See [all changes from v1](../usage/CHANGES.md) and check out our [ROADMAP](./maintainers/ROADMAP.md).
+
+## API Stability Guarantee
+
+The assertions currently used by go-openapi projects constitute our **stable API**.
+These entry points will remain backward compatible. Other assertions may evolve as we refine the v2 API.
+
+---
+
+## See Also
+
+**Getting Started:**
+- [Examples](../usage/EXAMPLES.md) - Practical code examples for using testify v2
+- [Usage Guide](../usage/USAGE.md) - API conventions and navigation guide
+- [Migration Guide](../usage/MIGRATION.md) - Migrating from stretchr/testify v1
+
+**Project Documentation:**
+- [Changes from v1](../usage/CHANGES.md) - Complete list of changes and new features
+- [Roadmap](./maintainers/ROADMAP.md) - Future development plans
+- [Architecture](./maintainers/ARCHITECTURE.md) - Technical architecture and design decisions
+- [Contributing](./contributing/CONTRIBUTING.md) - How to contribute to this project
+- [The original README](./maintainers/ORIGINAL.md)
+
+---
 
 <!-- Badges: status  -->
 [test-badge]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml/badge.svg

docs/doc-site/project/contributing/CONTRIBUTORS.md

@@ -4,6 +4,11 @@ description: Acknowledgements to all-time contributors
 weight: 10
 ---
 
+{{% notice primary "TL;DR" "meteor" %}}
+> Recognition and thanks to all 256 contributors who have helped build testify from its origins to this fork.
+> Complete list of contributors with commit counts and links to their contributions.
+{{% /notice %}}
+
 ## Emeritus
 
 We thank these members for their service to this community.

docs/doc-site/project/maintainers/ARCHITECTURE.md

@@ -41,6 +41,8 @@ The generator scans `internal/assertions/` and produces:
 
 **Generated Packages: `assert/` and `require/`**
 
+**Generated Documentation: `docs/doc-site/api/`**
+
 Everything in these packages is generated. Never edit generated files directly.
 
 Exceptions: