Doc improvements

Author: Tinche

docs/index.md

@@ -14,9 +14,10 @@ strategies
 validation
 preconf
 unions
+history
 benchmarking
 contributing
-history
+API <modules>
 ```
 
 ```{include} ../README.md

docs/structuring.md

@@ -154,7 +154,7 @@ to deques are:
 - `Deque[T]`
 - `deque[T]`
 
-In all cases, a new **unbounded** deque (`maxlen=None`) will be returned, 
+In all cases, a new **unbounded** deque (`maxlen=None`) will be returned,
 so this operation can be used to copy an iterable into a deque.
 If you want to convert into bounded `deque`, registering a custom structuring hook is a good approach.
 
@@ -173,6 +173,7 @@ deque(['1', None, '3'])
 ```
 
 ```{versionadded} 23.1.0
+
 ```
 
 ### Sets and Frozensets
@@ -384,10 +385,10 @@ Another option is to use a custom tagged union strategy (see [Strategies - Tagge
 [PEP 593](https://www.python.org/dev/peps/pep-0593/) annotations (`typing.Annotated[type, ...]`) are supported and are
 matched using the first type present in the annotated type.
 
-### `typing.NewType`
+## `typing.NewType`
 
 [NewTypes](https://docs.python.org/3/library/typing.html#newtype) are supported and are structured according to the rules for their underlying type.
-Their hooks can also be overriden using :py:attr:`cattrs.Converter.register_structure_hook`.
+Their hooks can also be overriden using {meth}`Converter.register_structure_hook() <cattrs.BaseConverter.register_structure_hook>`.
 
 ```{doctest}
 

docs/unions.md

@@ -1,10 +1,14 @@
-# Tips for handling unions
+# Tips for Handling Unions
 
 This sections contains information for advanced union handling.
 
-As mentioned in the structuring section, _cattrs_ is able to handle simple
-unions of _attrs_ classes automatically. More complex cases require
-converter customization (since there are many ways of handling unions).
+As mentioned in the structuring section, _cattrs_ is able to handle simple unions of _attrs_ classes automatically.
+More complex cases require converter customization (since there are many ways of handling unions).
+
+_cattrs_ also comes with a number of strategies to help handle unions:
+
+- [tagged unions strategy](strategies.md#tagged-unions-strategy) mentioned below
+- [union passthrough strategy](strategies.md#union-passthrough), which is preapplied to all the [preconfigured](preconf.md) converters
 
 ## Unstructuring unions with extra metadata
 

src/cattrs/converters.py

@@ -279,11 +279,10 @@ def register_unstructure_hook_factory(
         """
         Register a hook factory for a given predicate.
 
-        A predicate is a function that, given a type, returns whether the factory
-        can produce a hook for that type.
-
-        A factory is a callable that, given a type, produces an unstructuring
-        hook for that type. This unstructuring hook will be cached.
+        :param predicate: A function that, given a type, returns whether the factory
+            can produce a hook for that type.
+        :param factory: A callable that, given a type, produces an unstructuring
+            hook for that type. This unstructuring hook will be cached.
         """
         self._unstructure_func.register_func_list([(predicate, factory, True)])
 
@@ -326,11 +325,10 @@ def register_structure_hook_factory(
         """
         Register a hook factory for a given predicate.
 
-        A predicate is a function that, given a type, returns whether the factory
-        can produce a hook for that type.
-
-        A factory is a callable that, given a type, produces a structuring
-        hook for that type. This structuring hook will be cached.
+        :param predicate: A function that, given a type, returns whether the factory
+            can produce a hook for that type.
+        :param factory: A callable that, given a type, produces a structuring
+            hook for that type. This structuring hook will be cached.
         """
         self._structure_func.register_func_list([(predicate, factory, True)])