hypothesis: add docs.

Author: pradeep90

CHANGELOG.md

@@ -28,6 +28,8 @@ See [0Ver](https://0ver.org/).
 
 - Make `hypothesis` plugin test laws from user-defined interfaces too
 - Make `hypothesis` plugin accept user-defined strategies
+- Allow users to override the `hypothesis` plugin's strategies for types, such
+  as `TypeVar` and `Callable`.
 
 ### Bugfixes
 

docs/pages/contrib/hypothesis_plugins.rst

@@ -32,40 +32,8 @@ So, you don't have to. Example:
 
   assert st.from_type(Result).example()
 
-This is a convenience thing only.
-
-
-strategy_from_container
------------------------
-
-We provide a utility function
-to create ``hypothesis`` strategy from any container.
-
-You can use it to easily register your own containers.
-
-.. code:: python
-
-  from hypothesis import strategies as st
-  from returns.contrib.hypothesis.containers import strategy_from_container
-
-  st.register_type_strategy(
-      YourContainerClass,
-      strategy_from_container(YourContainerClass),
-  )
-
-You can also pass ``use_init`` keyword argument
-if you wish to use ``__init__`` method to instantiate your containers.
-Turned off by default.
-Example:
-
-.. code:: python
-
-  st.register_type_strategy(
-      YourContainerClass,
-      strategy_from_container(YourContainerClass, use_init=True),
-  )
-
-Or you can write your own ``hypothesis`` strategy. It is also fine.
+This means you can use ``Result``, ``Maybe``, etc. in your own property tests,
+and ``hypothesis`` will generate values for them as expected.
 
 
 check_all_laws
@@ -140,8 +108,26 @@ like ``Future``, ``ReaderFutureResult``, etc
 that have complex ``__init__`` signatures.
 And we don't want to mess with them.
 
-You can also register a custom strategy to be used when running your
-container's laws:
+Warning::
+  Checking laws is not compatible with ``pytest-xdist``,
+  because we use a lot of global mutable state there.
+  Please, use ``returns_lawful`` marker
+  to exclude them from ``pytest-xdist`` execution plan.
+
+
+Registering Custom Strategies when Checking Laws
+------------------------------------------------
+
+``hypothesis`` works by looking up strategies for the provided type
+annotations. Given that the types provided by ``returns`` are very complicated
+and not really native to Python, they may not be understood by ``hypothesis``,
+and you may get runtime exceptions such as ``ResolutionFailed``.
+
+In such cases, you may want to register custom strategies for types for which
+``hypothesis`` does not find any strategies.
+
+The main use case is registering a custom strategy to generate your container
+when running its laws:
 
 .. code:: python
 
@@ -150,22 +136,64 @@ container's laws:
 
   check_all_laws(Number, container_strategy=st.builds(Number, st.integers()))
 
-The ``container_strategy`` will be used only when running the tests generated
-by the ``check_all_laws`` call above. It will have no effect on any other
-property tests that involve ``Number``. You cannot use this argument together
-with ``use_init``.
+You can also register strategies for other types:
+
+.. code:: python
+
+
+  from hypothesis import strategies as st
+
+  check_all_laws(
+      Number,
+      container_strategy=st.builds(Number, st.integers()),
+      other_strategies={Foo: st.builds(Foo, st.text())},
+  )
+
+These custom strategies will be used only when running the tests generated by
+the ``check_all_laws`` call above. They will have no effect on any other
+property tests that involve the same types. You cannot use this argument
+together with ``use_init``.
+
+
+Registering Custom Strategies outside Law Tests
+-----------------------------------------------
+
+We provide a utility function
+to create ``hypothesis`` strategy from any container:
+``strategy_from_container``.
+
+You can use it to register your own containers.
+
+.. code:: python
+
+  from hypothesis import strategies as st
+  from returns.contrib.hypothesis.containers import strategy_from_container
+
+  st.register_type_strategy(
+      YourContainerClass,
+      strategy_from_container(YourContainerClass),
+  )
+
+You can also pass ``use_init`` keyword argument
+if you wish to use ``__init__`` method to instantiate your containers.
+Turned off by default.
+Example:
+
+.. code:: python
+
+  st.register_type_strategy(
+      YourContainerClass,
+      strategy_from_container(YourContainerClass, use_init=True),
+  )
+
+Or you can write your own ``hypothesis`` strategy. It is also fine.
 
 Warning::
   Avoid directly registering your container's strategy with ``hypothesis``
   using ``st.register_type_strategy``. Because of the way we emulate
-  higher-kinded types, ``hypothesis`` may mistakenly use the strategy
-  for other incompatible containers and cause spurious test failures.
-
-Warning::
-  Checking laws is not compatible with ``pytest-xdist``,
-  because we use a lot of global mutable state there.
-  Please, use ``returns_lawful`` marker
-  to exclude them from ``pytest-xdist`` execution plan.
+  higher-kinded types, ``hypothesis`` may mistakenly use the strategy for
+  other incompatible containers and cause spurious test failures. We specify
+  how to do it just in case you need it and you know what you're doing.
 
 
 Further reading

tests/test_contrib/test_hypothesis/test_laws/test_custom_strategy_for_callable.py

@@ -6,7 +6,8 @@
 
 Without the custom strategy, we would simply get instances of `_Wrapper`, even
 though it is not an `Applicative`, because `_Wrapper` is a subtype of `KindN`
-and `hypothesis` doesn't know about that `KindN` is just emulating HKTs.
+and `hypothesis` doesn't know about the fact that `KindN` is just emulating
+HKTs.
 """
 
 from abc import abstractmethod