Merge pull request #2053 from serahrono/update-hypothesis-docs

Update hypothesis docs

guides/documentation.rst

@@ -36,8 +36,8 @@ cross-references.  Without repeating the docs for Sphinx, here are some tips:
   use autodoc to insert and interpret the docstring.
 
 - When referencing a function, you can insert a reference to a function as
-  (eg) ``:func:`hypothesis.given`\ ``, which will appear as
-  ``hypothesis.given()`` with a hyperlink to the apropriate docs.  You can
+  (eg) ``:func:`hypothesis.given`\``, which will appear as
+  ``hypothesis.given()`` with a hyperlink to the appropriate docs.  You can
   show only the last part (unqualified name) by adding a tilde at the start,
   like ``:func:`~hypothesis.given`\ `` -> ``given()``.  Finally, you can give
   it alternative link text in the usual way:

guides/strategies-that-shrink.rst

@@ -57,10 +57,10 @@ where magnitude constraints were added to the ``complex_numbers`` strategy,
 makes a nice case study.  We wanted to continue shrinking the real and
 imaginary parts like ``builds(complex, floats(), floats())``.
 
-In a worst-case scenario, the performance of filtering could be arbitarily
+In a worst-case scenario, the performance of filtering could be arbitrarily
 bad, while a 'generate and scale' approach would mean that simple inputs
 could lead to irrational outputs.  Instead, we choose an imaginary part
-between +/- max_magnitute, then calculate the resulting bounds on the real
+between +/- max_magnitude, then calculate the resulting bounds on the real
 part and draw it from a strategy that will always be valid.  This ensures
 that the imaginary part shrinks to zero first, as we think real-valued
 complex numbers are simpler than imaginary-valued complex numbers.
@@ -82,7 +82,7 @@ allowed by the bounds and tz strategy!
 Eliding much of the detail, a key part is to find such a moment between two
 endpoints, when we can only check whether one or more exists.  The traditional
 approach would be to use a binary search, but this would be relatively expensive
-to shrink as we would pay the log-n cost on every attemted shrink.
+to shrink as we would pay the log-n cost on every attempted shrink.
 
 Instead of choosing the midpoint, we draw a *random* point between our known
 endpoints, and repeat this until we find a satisfactory moment.  This allows
@@ -127,7 +127,7 @@ valid (and preferably local) shrinks to the final example.  For example:
         draw(...)
         ...
 
-    # In this form, the shrinker can see a repeated struture of labels
+    # In this form, the shrinker can see a repeated structure of labels
     # and delete one loop iteration without touching anything else.
     # We use a variant of this trick to generate collections internally!
     while draw(integers(0, x)) > threshold:
@@ -140,7 +140,8 @@ object at the same time, again so they can be modified or deleted together.
 
 The exact behaviour of the shrinking is a topic of active research and
 development, so if you are interested in the details we recommend reading
-the "internals.rst" guide and the well-commented source code in
+the `internals guide <https://github.com/HypothesisWorks/hypothesis/blob/master/guides/internals.rst>`_
+and the well-commented source code in
 ``hypothesis.internal.conjecture``.  An earlier (mid-2018) version is
 illustrated in David's draft paper *Test-Case Reduction for Free*,
 along with an extensive evaluation.  Contact him if you would like a copy.
@@ -153,7 +154,7 @@ The last section is for current or prospective Hypothesis contributors only.
 
 These tricks rely on implementation details that are not available to
 third-party libraries or users, **and can change in any patch release**.
-Occasionally they are also indispensible to get good performance in underlying
+Occasionally they are also indispensable to get good performance in underlying
 primitives, so please contact us if the public API is not enough and we may
 be able to work something out.
 
@@ -208,9 +209,9 @@ When the shrinker tries to delete the first two draws, the resulting buffer
 will lead to the same rule being chosen at step *one* instead.  We've made
 our own luck!
 
-This trick is expecially useful when we want to avoid rejection sampling
+This trick is especially useful when we want to avoid rejection sampling
 (the ``.filter`` method, ``assume``) for performance reasons, but also
-need to give the shrinker the same low-level represention for each instance
+need to give the shrinker the same low-level representation for each instance
 of a repeated choice.
 
 
@@ -257,7 +258,7 @@ deleted simultaneously using ``data.start_example``.  This is used to group
 the value and sign of floating-point numbers, for example, which we split up
 in order to provide a more natural shrinking order.
 
-Explict example management can also be useful to delineate variably-sized
+Explicit example management can also be useful to delineate variably-sized
 draws, such as our internal helper ``cu.biased_coin``, which makes eliminating
 dead bytes much cheaper.  Finally, labelling otherwise indistinguishable draws
 means the shrinker can attempt to swap only the like values.

hypothesis-python/RELEASE.rst

@@ -0,0 +1,7 @@
+RELEASE_TYPE: patch
+
+This patch improves the docstrings of several Hypothesis strategies, by
+clarifying markup and adding cross-references.  There is no runtime change.
+
+Thanks to Elizabeth Williams and Serah Njambi Rono for their contributions
+at the SciPy 2019 sprints!

hypothesis-python/docs/community.rst

@@ -16,7 +16,7 @@ Hypothesis related at all.  If you post a question on StackOverflow, please use
 Please note that `the Hypothesis code of conduct <https://github.com/HypothesisWorks/hypothesis/blob/master/CODE_OF_CONDUCT.rst>`_
 applies in all Hypothesis community spaces.
 
-If you would like to cite Hypothesis, please consider `our sugested citation
+If you would like to cite Hypothesis, please consider `our suggested citation
 <https://github.com/HypothesisWorks/hypothesis/blob/master/CITATION>`_.
 
 If you like repo badges, we suggest the following badge, which you can add

hypothesis-python/docs/details.rst

@@ -484,7 +484,7 @@ Making random code deterministic
 --------------------------------
 
 While Hypothesis' example generation can be used for nondeterministic tests,
-debugging anything nondeterministic is usually a very frustrating excercise.
+debugging anything nondeterministic is usually a very frustrating exercise.
 To make things worse, our example *shrinking* relies on the same input
 causing the same failure each time - though we show the un-shrunk failure
 and a decent error message if it doesn't.

hypothesis-python/docs/supported.rst

@@ -12,7 +12,7 @@ Python versions
 ---------------
 
 Hypothesis is supported and tested on CPython 2.7 and CPython 3.5+, i.e.
-`all versisions of CPython with upstream support <https://devguide.python.org/#status-of-python-branches>`_,
+`all versions of CPython with upstream support <https://devguide.python.org/#status-of-python-branches>`_,
 
 Hypothesis also supports the latest PyPy for both Python 2 (until 2020) and Python 3.
 Hypothesis does not currently work on Jython,
@@ -90,7 +90,7 @@ Regularly verifying this
 Everything mentioned above as explicitly supported is checked on every commit
 with `Travis <https://travis-ci.org/HypothesisWorks/hypothesis>`__, and
 `Azure Pipelines <https://dev.azure.com/HypothesisWorks/Hypothesis/>`__.
-Our continous delivery pipeline runs all of these checks before publishing
+Our continuous delivery pipeline runs all of these checks before publishing
 each release, so when we say they're supported we really mean it.
 
 -------------------

hypothesis-python/src/hypothesis/_strategies.py

@@ -723,14 +723,13 @@ def lists(
     # type: (...) -> SearchStrategy[List[Ex]]
     """Returns a list containing values drawn from elements with length in the
     interval [min_size, max_size] (no bounds in that direction if these are
-    None). If max_size is 0 then elements may be None and only the empty list
-    will be drawn.
+    None). If max_size is 0, only the empty list will be drawn.
 
-    If unique is True (or something that evaluates to True), we compare direct
+    If ``unique`` is True (or something that evaluates to True), we compare direct
     object equality, as if unique_by was ``lambda x: x``. This comparison only
     works for hashable types.
 
-    If unique_by is not None it must be a callable or tuple of callables
+    If ``unique_by`` is not None it must be a callable or tuple of callables
     returning a hashable type when given a value drawn from elements. The
     resulting list will satisfy the condition that for ``i`` != ``j``,
     ``unique_by(result[i])`` != ``unique_by(result[j])``.
@@ -904,10 +903,11 @@ def dictionaries(
     # type: (...) -> SearchStrategy[Dict[Ex, T]]
     # Describing the exact dict_class to Mypy drops the key and value types,
     # so we report Dict[K, V] instead of Mapping[Any, Any] for now.  Sorry!
-    """Generates dictionaries of type dict_class with keys drawn from the keys
-    argument and values drawn from the values argument.
+    """Generates dictionaries of type ``dict_class`` with keys drawn from the ``keys``
+    argument and values drawn from the ``values`` argument.
 
-    The size parameters have the same interpretation as for lists.
+    The size parameters have the same interpretation as for
+    :func:`~hypothesis.strategies.lists`.
 
     Examples from this strategy shrink by trying to remove keys from the
     generated dictionary, and by shrinking each generated key and value.
@@ -1043,15 +1043,15 @@ def text(
 ):
     # type: (...) -> SearchStrategy[Text]
     """Generates values of a unicode text type (unicode on python 2, str on
-    python 3) with values drawn from alphabet, which should be an iterable of
+    python 3) with values drawn from ``alphabet``, which should be an iterable of
     length one strings or a strategy generating such strings.
 
     The default alphabet strategy can generate the full unicode range but
     excludes surrogate characters because they are invalid in the UTF-8
     encoding.  You can use :func:`~hypothesis.strategies.characters` without
     arguments to find surrogate-related bugs such as :bpo:`34454`.
 
-    min_size and max_size have the usual interpretations.
+    ``min_size`` and ``max_size`` have the usual interpretations.
     Note that Python measures string length by counting codepoints: U+00C5
     ``Å`` is a single character, while U+0041 U+030A ``Å`` is two - the ``A``,
     and a combining ring above.
@@ -1445,13 +1445,13 @@ def fractions(
     # type: (...) -> SearchStrategy[Fraction]
     """Returns a strategy which generates Fractions.
 
-    If min_value is not None then all generated values are no less than
-    min_value.  If max_value is not None then all generated values are no
-    greater than max_value.  min_value and max_value may be anything accepted
+    If ``min_value`` is not None then all generated values are no less than
+    ``min_value``.  If ``max_value`` is not None then all generated values are no
+    greater than ``max_value``.  ``min_value`` and ``max_value`` may be anything accepted
     by the :class:`~fractions.Fraction` constructor.
 
-    If max_denominator is not None then the denominator of any generated
-    values is no greater than max_denominator. Note that max_denominator must
+    If ``max_denominator`` is not None then the denominator of any generated
+    values is no greater than ``max_denominator``. Note that ``max_denominator`` must
     be None or a positive integer.
 
     Examples from this strategy shrink towards smaller denominators, then