docs: say which dialects, shapes and zones are read

Author: Solganis

docs/extending/integrations.md

@@ -54,7 +54,9 @@ renders them as a collapsible tree and downstream tooling can parse them.
 Anything JSON cannot express degrades to a marked fallback instead of failing the attachment:
 
 - `{"__repr__": "..."}` for arbitrary objects, datetimes, non-finite floats, and circular references
-- `{"__type__": "set", "__data__": [...]}` for sets.
+- `{"__type__": "set", "__data__": [...]}` for sets
+- `{"__type__": "dict", "__data__": [[key, value], ...]}` for a mapping with any non-string key, since a
+  JSON object has string keys only and rendering `1` as `"1"` drops whichever of the two came second.
 
 Oversized values are capped: strings at 4000 chars, containers at 100 items.
 
@@ -271,7 +273,9 @@ On failure the library's own detailed diff is carried in the assertion message.
 
 Two array assertions, both accepting any array-like numpy can coerce:
 
-- `is_array_equal()` - exact, via `numpy.testing.assert_array_equal`
+- `is_array_equal()` - exact, via `numpy.testing.assert_array_equal`, with the shapes compared first, so a
+  scalar is not broadcast over an array (pass `strict=False` to let numpy broadcast, or `strict=True` to
+  compare dtypes too)
 - `is_array_close_to()` - float-tolerant, via `numpy.testing.assert_allclose`, for comparing computed
   arrays.
 

docs/guides/assertions.md

@@ -653,7 +653,9 @@ assert_that(naive).is_before(aware)                      # TypeError
 assert_that(naive).is_equal_to_ignoring_seconds(aware)   # TypeError
 ```
 
-Make both aware or both naive first, then the comparison is well defined.
+Make both aware or both naive first, then the comparison is well defined. Two aware values need not share
+a zone: the `ignoring_*` assertions read the expected side on the subject's clock before comparing, so
+`12:00Z` and `17:00+05:00` are the same instant to the second, and `12:00+05:00` is not.
 
 Equality can ignore units of time, and the numeric comparisons work on dates too:
 

docs/guides/data.md

@@ -84,10 +84,13 @@ the other assertion libraries here offer.
 
 Three spec dialects are read:
 
-- **OpenAPI 3.1**, as written
+- **OpenAPI 3.1 and 3.2**, as written: both carry JSON Schema 2020-12
 - **OpenAPI 3.0**, including its `nullable` keyword
 - **Swagger 2.0**, where the schema sits directly on the response, including its `x-nullable` extension
 
+A spec declaring any other `openapi` version is refused. Read as one of these it would validate against
+the wrong dialect, which passes every keyword that dialect cannot spell.
+
 Inside any of them, `$ref`, `oneOf` / `allOf` / `anyOf`, `enum` and `format` validate with full
 JSON-Schema semantics.
 

docs/reference/async.md

@@ -18,5 +18,13 @@ callable value, chain the assertion you expect to eventually hold, and await the
       show_root_toc_entry: true
 
 ::: assertpy2.async_assertions.AsyncAssertionBuilder
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
 
 ::: assertpy2.async_assertions.SyncAssertionBuilder
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true

docs/reference/entry-points.md

@@ -29,6 +29,12 @@ drives editor autocomplete.
       show_root_full_path: false
       show_root_toc_entry: true
 
+::: assertpy2.assertpy.NegatedBuilder
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
+
 ::: assertpy2.outcome.AssertionOutcome
     options:
       show_root_heading: true
@@ -51,11 +57,23 @@ drives editor autocomplete.
       show_root_heading: true
       show_root_toc_entry: true
 
+::: assertpy2.assertpy.WarningLoggingAdapter
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
+
 ::: assertpy2.assertpy.soft_assertions
     options:
       show_root_heading: true
       show_root_toc_entry: true
 
+::: assertpy2.assertpy.SoftAssertionCollector
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
+
 ::: assertpy2.assertpy.assert_all
     options:
       show_root_heading: true

docs/reference/errors.md

@@ -40,3 +40,15 @@ working unchanged. See [Errors & reporting](../guides/errors.md) for usage.
       show_root_heading: true
       show_root_full_path: false
       show_root_toc_entry: true
+
+::: assertpy2.errors.DanglingAssertionWarning
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
+
+::: assertpy2.errors.VacuousAssertionWarning
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true

docs/reference/matchers.md

@@ -19,3 +19,27 @@ and ``~``. See the [Matchers guide](../guides/matchers.md) for usage, compositio
       show_root_heading: true
       show_root_full_path: false
       show_root_toc_entry: true
+
+::: assertpy2.matchers.Matcher
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
+
+::: assertpy2.matchers.register_matcher
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
+
+::: assertpy2.matchers.unregister_matcher
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true
+
+::: assertpy2.matchers.clear_custom_matchers
+    options:
+      show_root_heading: true
+      show_root_full_path: false
+      show_root_toc_entry: true