Merge pull request #4418 from tybug/docs-cleanup

Improve `@example` docs

Author: tybug

hypothesis-python/RELEASE.rst

@@ -0,0 +1,3 @@
+RELEASE_TYPE: patch
+
+Improve documentation of |@example|.

hypothesis-python/docs/changelog.rst

@@ -6925,8 +6925,7 @@ This release consists of some internal refactoring to the shrinker in preparatio
 5.18.0 - 2020-06-22
 -------------------
 
-This release teaches Hypothesis to :ref:`shorten tracebacks <v3.79.2>` for
-:ref:`explicit examples <providing-explicit-examples>`, as we already do
+This release teaches Hypothesis to :ref:`shorten tracebacks <v3.79.2>` for |@example|, as we already do
 for generated examples, so that you can focus on your code rather than ours.
 
 If you have multiple failing explicit examples, they will now all be reported.
@@ -10874,7 +10873,7 @@ and adds a CI check so we don't add new ones.
 This patch fixes two bugs (:issue:`944` and :issue:`1521`), where messages
 about :func:`@seed <hypothesis.seed>` did not check the current verbosity
 setting, and the wrong settings were active while executing
-:ref:`explicit examples <providing-explicit-examples>`.
+explicit examples from |@example|.
 
 .. _v3.71.5:
 

hypothesis-python/docs/conf.py

@@ -116,7 +116,7 @@ def setup(app):
 
 
 language = "en"
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "prolog.rst"]
 pygments_style = "sphinx"
 todo_include_todos = False
 
@@ -166,168 +166,7 @@ def setup(app):
 
 autodoc_mock_imports = ["numpy", "pandas", "redis", "django", "pytz"]
 
-rst_prolog = """
-.. |given| replace:: :func:`~hypothesis.given`
-.. |@given| replace:: :func:`@given <hypothesis.given>`
-.. |@example| replace:: :func:`@example <hypothesis.example>`
-.. |@example.xfail| replace:: :func:`@example(...).xfail() <hypothesis.example.xfail>`
-.. |@settings| replace:: :func:`@settings <hypothesis.settings>`
-.. |settings| replace:: :func:`settings <hypothesis.settings>`
-.. |@composite| replace:: :func:`@composite <hypothesis.strategies.composite>`
-.. |assume| replace:: :func:`~hypothesis.assume`
-.. |target| replace:: :func:`~hypothesis.target`
-.. |event| replace:: :func:`~hypothesis.event`
-.. |note| replace:: :func:`~hypothesis.note`
-
-.. |max_examples| replace:: :obj:`~hypothesis.settings.max_examples`
-.. |settings.max_examples| replace:: :obj:`settings.max_examples <hypothesis.settings.max_examples>`
-.. |settings.database| replace:: :obj:`settings.database <hypothesis.settings.database>`
-.. |settings.deadline| replace:: :obj:`settings.deadline <hypothesis.settings.deadline>`
-.. |settings.derandomize| replace:: :obj:`settings.derandomize <hypothesis.settings.derandomize>`
-.. |settings.phases| replace:: :obj:`settings.phases <hypothesis.settings.phases>`
-.. |settings.print_blob| replace:: :obj:`settings.print_blob <hypothesis.settings.print_blob>`
-.. |settings.report_multiple_bugs| replace:: :obj:`settings.report_multiple_bugs <hypothesis.settings.report_multiple_bugs>`
-.. |settings.verbosity| replace:: :obj:`settings.verbosity <hypothesis.settings.verbosity>`
-.. |settings.suppress_health_check| replace:: \
-    :obj:`settings.suppress_health_check <hypothesis.settings.suppress_health_check>`
-.. |settings.stateful_step_count| replace:: :obj:`settings.stateful_step_count <hypothesis.settings.stateful_step_count>`
-.. |settings.backend| replace:: :obj:`settings.backend <hypothesis.settings.backend>`
-
-.. |~settings.max_examples| replace:: :obj:`~hypothesis.settings.max_examples`
-.. |~settings.database| replace:: :obj:`~hypothesis.settings.database`
-.. |~settings.deadline| replace:: :obj:`~hypothesis.settings.deadline`
-.. |~settings.derandomize| replace:: :obj:`~hypothesis.settings.derandomize`
-.. |~settings.phases| replace:: :obj:`~hypothesis.settings.phases`
-.. |~settings.print_blob| replace:: :obj:`~hypothesis.settings.print_blob`
-.. |~settings.report_multiple_bugs| replace:: :obj:`~hypothesis.settings.report_multiple_bugs`
-.. |~settings.verbosity| replace:: :obj:`~hypothesis.settings.verbosity`
-.. |~settings.suppress_health_check| replace:: :obj:`~hypothesis.settings.suppress_health_check`
-.. |~settings.stateful_step_count| replace:: :obj:`~hypothesis.settings.stateful_step_count`
-.. |~settings.backend| replace:: :obj:`~hypothesis.settings.backend`
-
-.. |HealthCheck.data_too_large| replace:: :obj:`HealthCheck.data_too_large <hypothesis.HealthCheck.data_too_large>`
-.. |HealthCheck.filter_too_much| replace:: :obj:`HealthCheck.filter_too_much <hypothesis.HealthCheck.filter_too_much>`
-.. |HealthCheck.too_slow| replace:: :obj:`HealthCheck.too_slow <hypothesis.HealthCheck.too_slow>`
-.. |HealthCheck.function_scoped_fixture| replace:: \
-    :obj:`HealthCheck.function_scoped_fixture <hypothesis.HealthCheck.function_scoped_fixture>`
-.. |HealthCheck.differing_executors| replace:: \
-    :obj:`HealthCheck.differing_executors <hypothesis.HealthCheck.differing_executors>`
-.. |HealthCheck| replace:: :obj:`~hypothesis.HealthCheck`
-
-.. |Phase| replace:: :obj:`Phase <hypothesis.Phase>`
-.. |Phase.explicit| replace:: :obj:`Phase.explicit <hypothesis.Phase.explicit>`
-.. |Phase.reuse| replace:: :obj:`Phase.reuse <hypothesis.Phase.reuse>`
-.. |Phase.generate| replace:: :obj:`Phase.generate <hypothesis.Phase.generate>`
-.. |Phase.target| replace:: :obj:`Phase.target <hypothesis.Phase.target>`
-.. |Phase.shrink| replace:: :obj:`Phase.shrink <hypothesis.Phase.shrink>`
-.. |Phase.explain| replace:: :obj:`Phase.explain <hypothesis.Phase.explain>`
-
-.. |Verbosity| replace:: :obj:`~hypothesis.Verbosity`
-.. |Verbosity.verbose| replace:: :obj:`Verbosity.verbose <hypothesis.Verbosity.verbose>`
-.. |Verbosity.debug| replace:: :obj:`Verbosity.debug <hypothesis.Verbosity.debug>`
-.. |Verbosity.normal| replace:: :obj:`Verbosity.normal <hypothesis.Verbosity.normal>`
-.. |Verbosity.quiet| replace:: :obj:`Verbosity.quiet <hypothesis.Verbosity.quiet>`
-
-.. |InvalidArgument| replace:: :obj:`InvalidArgument <hypothesis.errors.InvalidArgument>`
-.. |DidNotReproduce| replace:: :obj:`DidNotReproduce <hypothesis.errors.DidNotReproduce>`
-
-.. |st.lists| replace:: :func:`~hypothesis.strategies.lists`
-.. |st.integers| replace:: :func:`~hypothesis.strategies.integers`
-.. |st.floats| replace:: :func:`~hypothesis.strategies.floats`
-.. |st.booleans| replace:: :func:`~hypothesis.strategies.booleans`
-.. |st.none| replace:: :func:`~hypothesis.strategies.none`
-.. |st.composite| replace:: :func:`@composite <hypothesis.strategies.composite>`
-.. |st.data| replace:: :func:`~hypothesis.strategies.data`
-.. |st.one_of| replace:: :func:`~hypothesis.strategies.one_of`
-.. |st.text| replace:: :func:`~hypothesis.strategies.text`
-.. |st.characters| replace:: :func:`~hypothesis.strategies.characters`
-.. |st.tuples| replace:: :func:`~hypothesis.strategies.tuples`
-.. |st.sets| replace:: :func:`~hypothesis.strategies.sets`
-.. |st.dictionaries| replace:: :func:`~hypothesis.strategies.dictionaries`
-.. |st.fixed_dictionaries| replace:: :func:`~hypothesis.strategies.fixed_dictionaries`
-.. |st.datetimes| replace:: :func:`~hypothesis.strategies.datetimes`
-.. |st.builds| replace:: :func:`~hypothesis.strategies.builds`
-.. |st.recursive| replace:: :func:`~hypothesis.strategies.recursive`
-.. |st.deferred| replace:: :func:`~hypothesis.strategies.deferred`
-.. |st.from_type| replace:: :func:`~hypothesis.strategies.from_type`
-.. |st.sampled_from| replace:: :func:`~hypothesis.strategies.sampled_from`
-.. |st.uuids| replace:: :func:`~hypothesis.strategies.uuids`
-.. |st.ip_addresses| replace:: :func:`~hypothesis.strategies.ip_addresses`
-.. |st.register_type_strategy| replace:: :func:`~hypothesis.strategies.register_type_strategy`
-.. |st.just| replace:: :func:`~hypothesis.strategies.just`
-.. |st.domains| replace:: :func:`~hypothesis.provisional.domains`
-.. |st.urls| replace:: :func:`~hypothesis.provisional.urls`
-
-.. |django.from_form| replace:: :func:`~hypothesis.extra.django.from_form`
-.. |django.from_model| replace:: :func:`~hypothesis.extra.django.from_model`
-.. |django.from_field| replace:: :func:`~hypothesis.extra.django.from_field`
-
-.. |settings.register_profile| replace:: :func:`~hypothesis.settings.register_profile`
-.. |settings.get_profile| replace:: :func:`~hypothesis.settings.get_profile`
-.. |settings.load_profile| replace:: :func:`~hypothesis.settings.load_profile`
-
-.. |SearchStrategy| replace:: :class:`~hypothesis.strategies.SearchStrategy`
-.. |.filter| replace:: :func:`.filter() <hypothesis.strategies.SearchStrategy.filter>`
-.. |.filter()| replace:: :func:`.filter() <hypothesis.strategies.SearchStrategy.filter>`
-.. |.flatmap| replace:: :func:`.flatmap() <hypothesis.strategies.SearchStrategy.flatmap>`
-.. |.flatmap()| replace:: :func:`.flatmap() <hypothesis.strategies.SearchStrategy.flatmap>`
-.. |.map| replace:: :func:`.map() <hypothesis.strategies.SearchStrategy.map>`
-.. |.map()| replace:: :func:`.map() <hypothesis.strategies.SearchStrategy.map>`
-.. |.example()| replace:: :func:`.example() <hypothesis.strategies.SearchStrategy.example>`
-
-.. |PrimitiveProvider| replace:: :class:`~hypothesis.internal.conjecture.providers.PrimitiveProvider`
-.. |PrimitiveProvider.realize| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.realize`
-.. |PrimitiveProvider.draw_integer| replace:: \
-    :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_integer`
-.. |PrimitiveProvider.draw_boolean| replace:: \
-    :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_boolean`
-.. |PrimitiveProvider.draw_float| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_float`
-.. |PrimitiveProvider.draw_string| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_string`
-.. |PrimitiveProvider.draw_bytes| replace:: :func:`~hypothesis.internal.conjecture.providers.PrimitiveProvider.draw_bytes`
-
-.. |AVAILABLE_PROVIDERS| replace:: :data:`~hypothesis.internal.conjecture.providers.AVAILABLE_PROVIDERS`
-.. |TESTCASE_CALLBACKS| replace:: :data:`~hypothesis.internal.observability.TESTCASE_CALLBACKS`
-.. |BUFFER_SIZE| replace:: :data:`~hypothesis.internal.conjecture.engine.BUFFER_SIZE`
-.. |MAX_SHRINKS| replace:: :data:`~hypothesis.internal.conjecture.engine.MAX_SHRINKS`
-.. |MAX_SHRINKING_SECONDS| replace:: :data:`~hypothesis.internal.conjecture.engine.MAX_SHRINKING_SECONDS`
-.. |BackendCannotProceed| replace:: :exc:`~hypothesis.errors.BackendCannotProceed`
-
-.. |@rule| replace:: :func:`@rule <hypothesis.stateful.rule>`
-.. |RuleBasedStateMachine| replace:: :class:`~hypothesis.stateful.RuleBasedStateMachine`
-
-.. |@reproduce_failure| replace:: :func:`@reproduce_failure <hypothesis.reproduce_failure>`
-.. |@seed| replace:: :func:`@seed <hypothesis.seed>`
-
-.. |ExampleDatabase| replace:: :class:`~hypothesis.database.ExampleDatabase`
-.. |ExampleDatabase.save| replace:: :func:`~hypothesis.database.ExampleDatabase.save`
-.. |ExampleDatabase.delete| replace:: :func:`~hypothesis.database.ExampleDatabase.delete`
-.. |ExampleDatabase.fetch| replace:: :func:`~hypothesis.database.ExampleDatabase.fetch`
-.. |ExampleDatabase.move| replace:: :func:`~hypothesis.database.ExampleDatabase.move`
-.. |ExampleDatabase.add_listener| replace:: :func:`~hypothesis.database.ExampleDatabase.add_listener`
-.. |ExampleDatabase.remove_listener| replace:: :func:`~hypothesis.database.ExampleDatabase.remove_listener`
-.. |ExampleDatabase.clear_listeners| replace:: :func:`~hypothesis.database.ExampleDatabase.clear_listeners`
-.. |ExampleDatabase._start_listening| replace:: :func:`~hypothesis.database.ExampleDatabase._start_listening`
-.. |ExampleDatabase._stop_listening| replace:: :func:`~hypothesis.database.ExampleDatabase._stop_listening`
-.. |ExampleDatabase._broadcast_change| replace:: :func:`~hypothesis.database.ExampleDatabase._broadcast_change`
-
-.. |DirectoryBasedExampleDatabase| replace:: :class:`~hypothesis.database.DirectoryBasedExampleDatabase`
-.. |InMemoryExampleDatabase| replace:: :class:`~hypothesis.database.InMemoryExampleDatabase`
-.. |ReadOnlyDatabase| replace:: :class:`~hypothesis.database.ReadOnlyDatabase`
-.. |MultiplexedDatabase| replace:: :class:`~hypothesis.database.MultiplexedDatabase`
-.. |GitHubArtifactDatabase| replace:: :class:`~hypothesis.database.GitHubArtifactDatabase`
-.. |BackgroundWriteDatabase| replace:: :class:`~hypothesis.database.BackgroundWriteDatabase`
-.. |RedisExampleDatabase| replace:: :class:`~hypothesis.extra.redis.RedisExampleDatabase`
-
-.. |is_hypothesis_test| replace:: :func:`~hypothesis.is_hypothesis_test`
-
-.. |str| replace:: :obj:`python:str`
-.. |int| replace:: :obj:`python:int`
-.. |bool| replace:: :obj:`python:bool`
-.. |bytes| replace:: :obj:`python:bytes`
-.. |float| replace:: :obj:`python:float`
-.. |assert| replace:: :keyword:`python:assert`
-.. |dataclasses| replace:: :mod:`python:dataclasses`
-"""
+rst_prolog = (Path(__file__).parent / "prolog.rst").read_text()
 
 codeautolink_autodoc_inject = False
 codeautolink_global_preface = """

hypothesis-python/docs/extensions.rst

@@ -126,10 +126,7 @@ standard library. Strategies for other things are also welcome; anything with
 external dependencies just goes in ``hypothesis.extra``.
 
 Tools such as assertion helpers may also need to check whether the current
-test is using Hypothesis:
-
-.. autofunction:: hypothesis.currently_in_test_context
-
+test is using Hypothesis. For that, see |currently_in_test_context|.
 
 .. _entry-points:
 
@@ -139,9 +136,9 @@ Hypothesis integration via entry points
 
 If you would like to ship Hypothesis strategies for a custom type - either as
 part of the upstream library, or as a third-party extension, there's a catch:
-:func:`~hypothesis.strategies.from_type` only works after the corresponding
-call to :func:`~hypothesis.strategies.register_type_strategy`, and you'll have
-the same problem with :func:`~hypothesis.register_random`.  This means that
+|st.from_type| only works after the corresponding
+call to |st.register_type_strategy|, and you'll have
+the same problem with |register_random|.  This means that
 either
 
 - you have to try importing Hypothesis to register the strategy when *your*
@@ -251,9 +248,9 @@ Hypothesis includes the following backends:
 hypothesis
     The default backend.
 hypothesis-urandom
-    The same as the default backend, but uses ``/dev/urandom`` to back the randomness
-    behind its PRNG. The only reason to use this backend over the default is if you are also
-    using `Antithesis <https://antithesis.com/>`_, in which case this enables Antithesis
+    The same as the default backend, but uses ``/dev/urandom`` as its source of randomness,
+    instead of the standard PRNG in |random.Random|. The only reason to use this backend over the default ``backend="hypothesis"`` is if you are also
+    using `Antithesis <https://antithesis.com/>`_, in which case this allows Antithesis
     mutation of ``/dev/urandom`` to control the values generated by Hypothesis.
 
     ``/dev/urandom`` is not available on Windows, so we emit a warning and fall back to the
@@ -264,7 +261,7 @@ crosshair
 
     Requires ``pip install hypothesis[crosshair]``.
 
-You can change the backend for a test with the ``backend`` setting. For instance, after
+You can change the backend for a test with the |settings.backend| setting. For instance, after
 ``pip install hypothesis[crosshair]``, you can use :pypi:`crosshair <crosshair-tool>` to
 generate examples with SMT via the :pypi:`hypothesis-crosshair` backend:
 

hypothesis-python/docs/index.rst

@@ -58,7 +58,7 @@ Hypothesis is the property-based testing library for Python. With Hypothesis, yo
 
 You should start with the :doc:`tutorial <tutorial/index>`, or the more condensed :doc:`quickstart <quickstart>`.
 
-.. rst-class:: clearfix row
+.. rst-class:: row
 
 .. rst-class:: column column2 top-left
 
@@ -90,7 +90,7 @@ Commentary oriented towards deepening your understanding of Hypothesis.
 
 Technical API reference.
 
-.. rst-class:: clearfix row
+.. rst-class:: row
 
 .. toctree::
   :maxdepth: 1