docs: more documentation, scrubbed existing docs (#37)

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

README.md

@@ -14,7 +14,7 @@
 
 **The v2 our tests wanted**
 
-A set of `go` packages that provide tools for testifying that your code behaves as you intended.
+A set of `go` packages that provide tools for testifying (verifying) that your code behaves as you intended.
 
 This is the go-openapi fork of the great [testify](https://github.com/stretchr/testify) package.
 
@@ -25,7 +25,7 @@ Main features:
 
 * zero external dependencies
 * opt-in dependencies for extra features (e.g. asserting YAML, colorized output)
-* assertions using generic types (see [a basic example][example-with-generics-url])
+* assertions using generic types (see [a basic example][example-with-generics-url]). [Read the fully story with generics][doc-generics]
 * [searchable documentation][doc-url]
 
 ## Announcements
@@ -40,26 +40,42 @@ Or join our Slack channel: [![Slack Channel][slack-logo]![slack-badge]][slack-ur
 
 ### Status
 
-Design and exploration phase. Contributions and proposals are welcome.
+Design and exploration phase. Feedback, contributions and proposals are welcome.
 
 > **Recent news**
-> Fully refactored how assertions are generated and documented.
-> Fixed hangs & panics when using `spew`. Fuzzed `spew`.
-> Fixed go routine leaks with `EventuallyWithT` and co.
-> Added `Kind` & `NotKind`
-> Fix deterministic order of keys in diff
-> Fixed edge cases with `InDelta`, `InEpsilon`
-> Added opt-in support for colorized output
-> Introduced generics (round 1): 16 new type-safe assertions with generic types (added benchmark)
 >
-> See our [ROADMAP][roadmap].
+> ✅ Fully refactored how assertions are generated and documented.
+>
+> ✅ Fixed hangs & panics when using `spew`. Fuzzed `spew`.
+>
+> ✅  Fixed go routine leaks with `EventuallyWithT` and co.
+>
+> ✅ Added `Kind` & `NotKind`
+>
+> ✅ Fix deterministic order of keys in diff
+>
+> ✅ Fixed edge cases with `InDelta`, `InEpsilon`
+>
+> ✅ Fixed edge cases with `EqualValues`
+>
+> ✅ Fixed wrong logic with `IsNonIncreasing`, `InNonDecreasing`
+>
+> ✅ Added opt-in support for colorized output
+>
+> ✅ Introduced generics: 38 new type-safe assertions with generic types (doc: added usage guide, examples and benchmark)
+>
+> See also our [ROADMAP][doc-roadmap].
+
+## Getting started
 
-## Import this library in your project
+Import this library in your project like so.
 
 ```cmd
 go get github.com/go-openapi/testify/v2
 ```
 
+... and start writing tests. Look at our [examples][doc-examples].
+
 ## Basic usage
 
 `testify` simplifies your test assertions like so.
@@ -123,9 +139,10 @@ distributed with this fork, including internalized libraries.
 
 ## Other documentation
 
-* [Getting started](https://go-openapi.github.io/testify/examples/)
+* [Getting started][doc-examples]
+* [Usage](https://go-openapi.github.io/testify/usage/)
 * [Motivations](https://go-openapi.github.io/testify/project/readme)
-* [Roadmap][roadmap]
+* [Roadmap][doc-roadmap]
 * [Internal architecture](https://go-openapi.github.io/testify/project/maintainers/architecture)
 
 * [All-time contributors](./CONTRIBUTORS.md)
@@ -138,15 +155,15 @@ distributed with this fork, including internalized libraries.
 
 Maintainers can cut a new release by either:
 
-* running [this workflow](https://github.com/go-openapi/testify/actions/workflows/bump-release.yml) (recommended)
+* running [this workflow][ci-release-workflow] (recommended)
 * or :
   1. preparing go.mod files with the next tag, merge
   2. pushing a semver tag
   * signed tags are preferred
   * The tag message is prepended to release notes
 
 <!-- Doc links -->
-[roadmap]: https://go-openapi.github.io/testify/project/maintainers/roadmap
+[doc-roadmap]: https://go-openapi.github.io/testify/project/maintainers/roadmap
 <!-- Badges: status  -->
 [test-badge]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml/badge.svg
 [test-url]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml
@@ -169,6 +186,8 @@ Maintainers can cut a new release by either:
 <!-- Badges: documentation & support -->
 [doc-badge]: https://img.shields.io/badge/doc-site-blue?link=https%3A%2F%2Fgo-openapi.github.io%2Ftestify%2F
 [doc-url]: https://go-openapi.github.io/testify
+[doc-examples]: https://go-openapi.github.io/testify/usage/examples
+[doc-generics]: https://go-openapi.github.io/testify/usage/generics
 [example-with-generics-url]: https://go-openapi.github.io/testify#usage-with-generics
 [godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/testify
 [godoc-url]: http://pkg.go.dev/github.com/go-openapi/testify
@@ -186,3 +205,4 @@ Maintainers can cut a new release by either:
 [goversion-url]: https://github.com/go-openapi/testify/blob/master/go.mod
 [top-badge]: https://img.shields.io/github/languages/top/go-openapi/testify
 [commits-badge]: https://img.shields.io/github/commits-since/go-openapi/testify/latest
+[ci-release-workflow]: https://github.com/go-openapi/testify/actions/workflows/bump-release.yml

SECURITY.md

@@ -8,12 +8,30 @@ This policy outlines the commitment and practices of the go-openapi maintainers
 | ------- | ------------------ |
 | 2.1.x   | :white_check_mark: |
 
+## Vulnerability checks in place
+
+This repository uses automated vulnerability scans, at every merged commit and at least once a week.
+
+We use:
+
+* [`GitHub CodeQL`][codeql-url]
+* [`trivy`][trivy-url]
+* [`govulncheck`][govulncheck-url]
+
+Reports are centralized in github security reports and visible only to the maintainers.
+
 ## Reporting a vulnerability
 
 If you become aware of a security vulnerability that affects the current repository,
-please report it privately to the maintainers.
+**please report it privately to the maintainers**
+rather than opening a publicly visible GitHub issue.
+
+Please follow the instructions provided by github to [Privately report a security vulnerability][github-guidance-url].
 
-Please follow the instructions provided by github to
-[Privately report a security vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability).
+> [!NOTE]
+> On Github, navigate to the project's "Security" tab then click on "Report a vulnerability".
 
-TL;DR: on Github, navigate to the project's "Security" tab then click on "Report a vulnerability".
+[codeql-url]: https://github.com/github/codeql
+[trivy-url]: https://trivy.dev/docs/latest/getting-started
+[govulncheck-url]: https://go.dev/blog/govulncheck
+[github-guidance-url]: https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability

all-docs.md

@@ -0,0 +1,70 @@
+# Documentation map
+
+## internals
+
+* ./hack/doc-site/hugo/README.md
+* ./internal/difflib/README.md
+* ./internal/spew/README.md
+* ./internal/testintegration/README.md
+
+## repo
+
+* [x] ./README.md
+* [x] ./CONTRIBUTORS.md
+* [x] ./.github/CONTRIBUTING.md
+* [x] ./.github/DCO.md
+* [x] ./CODE_OF_CONDUCT.md
+* [x] ./SECURITY.md
+
+## site
+
+### API docs (generated)
+
+* ./docs/doc-site/api/yaml.md
+* ./docs/doc-site/api/number.md
+* ./docs/doc-site/api/_index.md
+* ./docs/doc-site/api/panic.md
+* ./docs/doc-site/api/string.md
+* ./docs/doc-site/api/equality.md
+* ./docs/doc-site/api/file.md
+* ./docs/doc-site/api/boolean.md
+* ./docs/doc-site/api/common.md
+* ./docs/doc-site/api/ordering.md
+* ./docs/doc-site/api/json.md
+* ./docs/doc-site/api/collection.md
+* ./docs/doc-site/api/time.md
+* ./docs/doc-site/api/comparison.md
+* ./docs/doc-site/api/error.md
+* ./docs/doc-site/api/testing.md
+* ./docs/doc-site/api/type.md
+* ./docs/doc-site/api/http.md
+* ./docs/doc-site/api/condition.md
+
+### project docs
+
+* [x] ./docs/doc-site/_index.md
+
+* [x] ./docs/doc-site/usage/_index.md
+* ./docs/doc-site/usage/TUTORIAL.md
+* ./docs/doc-site/usage/EXAMPLES.md
+* ./docs/doc-site/usage/GENERICS.md
+* [x] ./docs/doc-site/usage/CHANGES.md
+
+* [x] ./docs/doc-site/project/_index.md
+* [x] ./docs/doc-site/project/LICENSE.md
+* [x] ./docs/doc-site/project/NOTICE.md
+* [x] ./docs/doc-site/project/maintainers/_index.md
+* [x] ./docs/doc-site/project/maintainers/MAINTAINERS.md
+* ./docs/doc-site/project/maintainers/ARCHITECTURE.md
+* ./docs/doc-site/project/maintainers/CODEGEN.md
+* [x] ./docs/doc-site/project/maintainers/BENCHMARKS.md
+* [x] ./docs/doc-site/project/maintainers/ROADMAP.md
+* ./docs/doc-site/project/maintainers/ORIGINAL.md
+* ./docs/doc-site/project/README.md
+* [x] ./docs/doc-site/project/SECURITY.md
+* ./docs/doc-site/project/contributing/STYLE.md
+* [x] ./docs/doc-site/project/contributing/CONTRIBUTING.md
+* [x] ./docs/doc-site/project/contributing/_index.md
+* [x] ./docs/doc-site/project/contributing/CONTRIBUTORS.md
+* [x] ./docs/doc-site/project/contributing/DCO.md
+* [x] ./docs/doc-site/project/contributing/CODE_OF_CONDUCT.md

codegen/internal/generator/templates/doc_index.md.gotmpl

@@ -9,7 +9,7 @@ weight: 1
 modified: {{ date }}
 ---
 
-**Go testing assertions for the rest of us**
+**The v2 our tests wanted**
 
 The [`testify/v2`][testifyv2] package has a fairly large API surface.
 
@@ -25,7 +25,7 @@ with all documented exported variants documented in a more concise form than the
 
 ## Domains
 
-The `testify` API is organized in {{ .RefCount }} domains shown below.
+The `testify` API is organized in {{ .RefCount }} logical domains shown below.
 Each domain contains assertions regrouped by their use case (e.g. http, json, error).
 
 {{ print "{{" }}< children type="card" description="true" >{{ print "}}" }}

docs/doc-site/_index.md

@@ -18,43 +18,44 @@ This is the go-openapi fork of the great [testify](https://github.com/stretchr/t
 ### Status
 
 {{% button href="https://github.com/go-openapi/testify/fork" hint="fork me on github" style=primary icon=code-fork %}}Fork me{{% /button %}}
-Design and exploration phase. Contributions and proposals are welcome.
+Design and exploration phase. Feedback, contributions and proposals are welcome.
 
 ### Motivation
 
 From the maintainers of `testify`, it looks like a v2 will eventually be released, but they'll do it at their own pace.
 
-We like all the principles they put forward to build this v2. [See discussion about v2](https://github.com/stretchr/testify/discussions/1560)
+We like all the principles they exposed to build this v2. [See discussion about v2](https://github.com/stretchr/testify/discussions/1560).
 
 However, at `go-openapi` we would like to address the well-known issues in `testify` with different priorities.
 
 With this fork, we want to:
-1. remove all external dependencies.
-2. make it easy to maintain and extend.
-3. pare down some of the chrome that has been added over the years.
+1. [x] remove all external dependencies.
+2. [x] make it easy to maintain and extend.
+3. [x] pare down some of the chrome that has been added over the years.
 
 {{% notice style="primary" title="Extended hand" icon="hand" %}}
 We hope that this endeavor will help the original project with a live-drill of what a v2 could look like.
-Hopefully, some of our ideas here will eventually percolate back into the original project.
 
-We are always happy to discuss with people who face the same problems as we do: avoid breaking changes, 
+Hopefully, some of our ideas will eventually percolate back into the original project and help the wider 
+community of go developers write better, clearer test code.
+
+Feedback is welcome and we are always happy to discuss with people who face the same problems as we do: avoid breaking changes, 
 APIs that became bloated over a decade or so, uncontrolled dependencies, difficult choices when it comes to introduce
 breaking changes, conflicting demands from users etc.
 {{% /notice %}}
 
-More about our motivations in the project's [README](README.md#motivation).
-
+Find more about our motivations in the project's [README](README.md#motivation).
 You might also be curious about our [ROADMAP](project/maintainers/ROADMAP.md).
 
 ### Getting started
 
-To use this package in your projects:
+Import this library in your project like so.
 
 ```cmd
     go get github.com/go-openapi/testify/v2
 ```
 
-... and start writing tests. Look at our [examples](./examples/).
+... and start writing tests. Look at our [examples][doc-examples].
 
 ### Basic usage
 
@@ -109,6 +110,23 @@ A formatted variant suffixed with `Tf` is also exposed.
 
 Obviously, the `Assertion` type cannot be extended with generic methods, as of `go1.25`.
 
+{{< cards >}}
+{{% card title="EqualT" %}}
+```go
+    import (
+        "testing"
+
+        "github.com/go-openapi/testify/v2/require"
+    )
+    ...
+    
+    const expected = "Hello World"
+    var input := "World"
+
+	result := someRamblingTextGeneration(input)
+    require.EqualT(t, expected, result)
+```
+{{% /card %}}
 {{% card title="InDeltaT" %}}
 ```go
     import (
@@ -128,6 +146,7 @@ Obviously, the `Assertion` type cannot be extended with generic methods, as of `
     require.InDeltaT(t, expected, input, delta)
 ```
 {{% /card %}}
+{{< /cards >}}
 
 ## Licensing
 
@@ -140,17 +159,16 @@ distributed with this fork, including internalized libraries.
 
 ## Contributing
 
-Please feel free to submit issues, fork the repository and send pull requests!
-
-When submitting an issue, we ask that you please include a complete test function that demonstrates the issue.
-Extra credit for those using Testify to write the test code that demonstrates it.
+Feel free to submit issues, fork the repository and send pull requests!
 
 {{% notice style="primary" title="Info" icon="info" %}}
 Code generation is used. Run `go generate ./...` to update generated files.
 {{% /notice %}}
 
-See also the [CONTRIBUTING guidelines](./project/contributing/CONTRIBUTING.md).
+See also our [CONTRIBUTING guidelines](./project/contributing/CONTRIBUTING.md).
 
 ---
 
 {{< children type="card" description="true" >}}
+
+[doc-examples]: ./usage/examples

docs/doc-site/examples/_index.md

@@ -23,7 +23,7 @@ We use:
 * [`trivy`][trivy-url]
 * [`govulncheck`][govulncheck-url]
 
-Reports are centralized in github security reports and visible to the maintainers.
+Reports are centralized in github security reports and visible only to the maintainers.
 
 ## Reporting a vulnerability