Merge pull request #1575 from Zac-HD/check-docs

Run Sphinx in nitpick mode, fix broken cross-references

.gitignore

@@ -28,6 +28,7 @@ _build
 htmlcov
 build
 dist
+.doctrees/
 
 # encrypted files
 secrets.tar

hypothesis-python/RELEASE.rst

@@ -0,0 +1,4 @@
+RELEASE_TYPE: patch
+
+This release fixes the broken cross-references in our docs,
+and adds a CI check so we don't add new ones.

hypothesis-python/docs/changes.rst

@@ -28,7 +28,7 @@ information to the contrary.
 -------------------
 
 This patch fixes two bugs (:issue:`944` and :issue:`1521`), where messages
-about :func:`@seed <hypothesis.seed` did not check the current verbosity
+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>`.
 
@@ -993,7 +993,7 @@ arbitrary. This may cause different results between runs.
 3.56.10 - 2018-05-16
 --------------------
 
-This release makes :obj:`~hypothesis.settings.define_setting`
+This release makes ``hypothesis.settings.define_setting``
 a private method, which has the effect of hiding it from the
 documentation.
 
@@ -1082,7 +1082,7 @@ satisfy assumption, and disabling health checks).
 -------------------
 
 This release fixes a problem that was introduced in :ref:`3.56.0 <v3.56.0>`:
-Use of the :envvar:`HYPOTHESIS_VERBOSITY_LEVEL` environment variable was, rather
+Use of the ``HYPOTHESIS_VERBOSITY_LEVEL`` environment variable was, rather
 than deprecated, actually broken due to being read before various setup
 the deprecation path needed was done. It now works correctly (and emits a
 deprecation warning).
@@ -1107,9 +1107,9 @@ knowledge of our internals (:issue:`535`).
   than a user-controlled setting.
 - :obj:`~hypothesis.settings.min_satisfying_examples` is deprecated and
   disabled, due to overlap with the
-  :obj:`~hypothesis.settings.HealthCheck.filter_too_much` healthcheck
+  :obj:`~hypothesis.HealthCheck.filter_too_much` healthcheck
   and poor interaction with :obj:`~hypothesis.settings.max_examples`.
-- :envvar:`HYPOTHESIS_VERBOSITY_LEVEL` is now deprecated.  Set
+- ``HYPOTHESIS_VERBOSITY_LEVEL`` is now deprecated.  Set
   :obj:`~hypothesis.settings.verbosity` through the profile system instead.
 - Examples tried by :func:`~hypothesis.find` are now reported at ``debug``
   verbosity level (as well as ``verbose`` level).
@@ -1172,7 +1172,7 @@ It has no other user visible effects.
 
 This patch relaxes constraints in our tests on the expected values returned
 by the standard library function :func:`~python:math.hypot` and the internal
-helper function :func:`~hypothesis.internal.cathetus`, to fix near-exact
+helper function ``cathetus``, to fix near-exact
 test failures on some 32-bit systems used by downstream packagers.
 
 .. _v3.55.0:
@@ -1187,7 +1187,7 @@ This release includes several improvements to the handling of the
 - The :obj:`~hypothesis.settings.database_file` setting was a historical
   artefact, and you should just use :obj:`~hypothesis.settings.database`
   directly.
-- The :envvar:`HYPOTHESIS_DATABASE_FILE` environment variable is
+- The ``HYPOTHESIS_DATABASE_FILE`` environment variable is
   deprecated, in favor of :meth:`~hypothesis.settings.load_profile` and
   the :obj:`~hypothesis.settings.database` setting.
 - If you have not configured the example database at all and the default
@@ -1409,7 +1409,7 @@ with the standard library :mod:`python:unittest` module:
 
 - Applying :func:`@given <hypothesis.given>` to a non-test method which is
   overridden from :class:`python:unittest.TestCase`, such as ``setUp``,
-  raises :attr:`a new health check <hypothesis.settings.not_a_test_method>`.
+  raises :attr:`a new health check <hypothesis.HealthCheck.not_a_test_method>`.
   (:issue:`991`)
 - Using :meth:`~python:unittest.TestCase.subTest` within a test decorated
   with :func:`@given <hypothesis.given>` would leak intermediate results
@@ -1475,7 +1475,7 @@ existing code), and all other input is deprecated.
 3.45.5 - 2018-02-26
 -------------------
 
-This patch improves strategy inference in :mod:`hypothesis.extra.django`
+This patch improves strategy inference in ``hypothesis.extra.django``
 to account for some validators in addition to field type - see
 :issue:`1116` for ongoing work in this space.
 
@@ -2245,7 +2245,7 @@ This is a bugfix release:
 -------------------
 
 This release supports strategy inference for more field types in Django
-:func:`~hypothesis.extra.django.models` - you can now omit an argument for
+:func:`~hypothesis.extra.django.models.models` - you can now omit an argument for
 Date, Time, Duration, Slug, IP Address, and UUID fields.  (:issue:`642`)
 
 Strategy generation for fields with grouped choices now selects choices from
@@ -2523,7 +2523,7 @@ This release is an internal change that affects how Hypothesis handles
 calculating certain properties of strategies.
 
 The primary effect of this is that it fixes a bug where use of
-:func:`~hypothesis.deferred` could sometimes trigger an internal assertion
+:func:`~hypothesis.strategies.deferred` could sometimes trigger an internal assertion
 error. However the fix for this bug involved some moderately deep changes to
 how Hypothesis handles certain constructs so you may notice some additional
 knock-on effects.
@@ -2765,7 +2765,7 @@ This work was funded by `Stripe <https://stripe.com/>`_.
 
 This release fixes some extremely specific circumstances that probably have
 never occurred in the wild where users of
-:func:`~hypothesis.searchstrategy.deferred` might have seen a RuntimeError from
+:func:`~hypothesis.strategies.deferred` might have seen a :class:`python:RuntimeError` from
 too much recursion, usually in cases where no valid example could have been
 generated anyway.
 
@@ -3578,7 +3578,7 @@ This is a bug fix release, fixing a number of problems with the settings system:
 This is a bug fix release for a single bug:
 
 * On Windows when running two Hypothesis processes in parallel (e.g. using
-  pytest-xdist) they could race with each other and one would raise an exception
+  :pypi:`pytest-xdist`) they could race with each other and one would raise an exception
   due to the non-atomic nature of file renaming on Windows and the fact that you
   can't rename over an existing file. This is now fixed.
 
@@ -3590,8 +3590,9 @@ This is a bug fix release for a single bug:
 
 This release is entirely provided by `Lucas Wiman <https://github.com/lucaswiman>`_:
 
-Strategies constructed by :func:`~hypothesis.extra.django.models` will now respect much more of
-Django's validations out of the box. Wherever possible :meth:`~django:django.db.models.Model.full_clean` should
+Strategies constructed by :func:`~hypothesis.extra.django.models.models`
+will now respect much more of Django's validations out of the box.
+Wherever possible, :meth:`~django:django.db.models.Model.full_clean` should
 succeed.
 
 In particular:

hypothesis-python/docs/details.rst

@@ -22,6 +22,8 @@ Sometimes this isn't enough, either because you have values with a ``repr`` that
 isn't very descriptive or because you need to see the output of some
 intermediate steps of your test. That's where the ``note`` function comes in:
 
+.. autofunction:: hypothesis.note
+
 .. doctest::
 
     >>> from hypothesis import given, note, strategies as st
@@ -271,7 +273,7 @@ Defining strategies
 ---------------------
 
 The type of object that is used to explore the examples given to your test
-function is called a :class:`~hypothesis.SearchStrategy`.
+function is called a :class:`~hypothesis.strategies.SearchStrategy`.
 These are created using the functions
 exposed in the :mod:`hypothesis.strategies` module.
 
@@ -541,6 +543,8 @@ argument, to force this inference for arguments with a default value.
     >>> builds(func).example()
     [-6993, '']
 
+.. data:: hypothesis.infer
+
 :func:`@given <hypothesis.given>` does not perform any implicit inference
 for required arguments, as this would break compatibility with pytest fixtures.
 :const:`~hypothesis.infer` can be used as a keyword argument to explicitly
@@ -616,7 +620,9 @@ supported use-case, again on a best-effort provisional basis.  For example:
 
     def foo_strategy() -> SearchStrategy[Foo]: ...
 
-:class:`hypothesis.strategies.SearchStrategy` is the type of all strategy
+.. class:: hypothesis.strategies.SearchStrategy
+
+:class:`~hypothesis.strategies.SearchStrategy` is the type of all strategy
 objects.  It is a generic type, and covariant in the type of the examples
 it creates.  For example:
 

hypothesis-python/docs/django.rst

@@ -5,10 +5,12 @@ Hypothesis for Django users
 ===========================
 
 Hypothesis offers a number of features specific for Django testing, available
-in the :mod:`hypothesis[django]` :doc:`extra </extras>`.  This is tested
+in the ``hypothesis[django]`` :doc:`extra </extras>`.  This is tested
 against each supported series with mainstream or extended support -
 if you're still getting security patches, you can test with Hypothesis.
 
+.. class:: hypothesis.extra.django.TestCase
+
 Using it is quite straightforward: All you need to do is subclass
 :class:`hypothesis.extra.django.TestCase` or
 :class:`hypothesis.extra.django.TransactionTestCase`
@@ -20,6 +22,8 @@ multiple times and you don't want them to interfere with each other). Test cases
 on these classes that do not use
 :func:`@given <hypothesis.given>` will be run as normal.
 
+.. class:: hypothesis.extra.django.TransactionTestCase
+
 We recommend avoiding :class:`~hypothesis.extra.django.TransactionTestCase`
 unless you really have to run each test case in a database transaction.
 Because Hypothesis runs this in a loop, the performance problems it normally has

hypothesis-python/docs/healthchecks.rst

@@ -27,3 +27,19 @@ Using a value of ``HealthCheck.all()`` will disable all health checks.
 .. autoclass:: HealthCheck
    :undoc-members:
    :inherited-members:
+
+
+------------
+Deprecations
+------------
+
+We also use a range of custom exception and warning types, so you can see
+exactly where an error came from - or turn only our warnings into errors.
+
+.. autoclass:: hypothesis.errors.HypothesisDeprecationWarning
+
+Deprecated features will be continue to emit warnings for at least six
+months, and then be removed in the following major release.
+Note however that not all warnings are subject to this grace period;
+sometimes we strengthen validation by adding a warning and these may
+become errors immediately at a major release.

hypothesis-python/docs/numpy.rst

@@ -9,7 +9,7 @@ numpy
 -----
 
 Hypothesis offers a number of strategies for `NumPy <http://www.numpy.org/>`_ testing,
-available in the :mod:`hypothesis[numpy]` :doc:`extra </extras>`.
+available in the ``hypothesis[numpy]`` :doc:`extra </extras>`.
 It lives in the ``hypothesis.extra.numpy`` package.
 
 The centerpiece is the :func:`~hypothesis.extra.numpy.arrays` strategy, which generates arrays with

hypothesis-python/docs/settings.rst

@@ -59,7 +59,9 @@ Hypothesis divides tests into four logically distinct phases:
    one (explicit examples cannot be shrunk).
 
 The phases setting provides you with fine grained control over which of these run,
-with each phase corresponding to a value on the :class:`~hypothesis._settings.Phase` enum:
+with each phase corresponding to a value on the :class:`~hypothesis.Phase` enum:
+
+.. class:: hypothesis.Phase
 
 1. ``Phase.explicit`` controls whether explicit examples are run.
 2. ``Phase.reuse`` controls whether previous examples will be reused.
@@ -79,7 +81,7 @@ Seeing intermediate result
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To see what's going on while Hypothesis runs your tests, you can turn
-up the verbosity setting. This works with both :func:`~hypothesis.core.find`
+up the verbosity setting. This works with both :func:`~hypothesis.find`
 and :func:`@given <hypothesis.given>`.
 
 .. doctest::
@@ -176,6 +178,9 @@ so you are more likely to find bugs.
 Hypothesis allows you to define different settings profiles. These profiles
 can be loaded at any time.
 
+.. autoclass:: hypothesis.settings
+    :members: register_profile, get_profile, load_profile
+
 Loading a profile changes the default settings but will not change the behavior
 of tests that explicitly change the settings.
 

hypothesis-python/src/hypothesis/errors.py

@@ -163,6 +163,10 @@ class HypothesisDeprecationWarning(HypothesisWarning, FutureWarning):
 
     Actually inherits from FutureWarning, because DeprecationWarning is
     hidden by the default warnings filter.
+
+    You can configure the Python :mod:`python:warnings` to handle these
+    warnings differently to others, either turning them into errors or
+    suppressing them entirely.  Obviously we would prefer the former!
     """
 
 

hypothesis-python/src/hypothesis/extra/django/models.py

@@ -189,7 +189,7 @@ def models(
     - for best results, make sure your validators are derived from Django's
     and therefore have the known types and attributes.
     Passing a keyword argument skips inference for that field; pass a strategy
-    or pass :const:`hypothesis.extra.django.models.default_value` to skip
+    or pass ``hypothesis.extra.django.models.default_value`` to skip
     inference for that field.
 
     Foreign keys are not automatically derived. If they're nullable they will

hypothesis-python/src/hypothesis/extra/numpy.py

@@ -289,11 +289,11 @@ def arrays(
     unique=False,  # type: bool
 ):
     # type: (...) -> st.SearchStrategy[np.ndarray]
-    """Returns a strategy for generating :class:`numpy's
-    ndarrays<numpy.ndarray>`.
+    r"""Returns a strategy for generating :class:`numpy:numpy.ndarray`\ s.
 
-    * ``dtype`` may be any valid input to :class:`numpy.dtype <numpy.dtype>`
-      (this includes ``dtype`` objects), or a strategy that generates such
+    * ``dtype`` may be any valid input to
+      :class:`numpy.dtype <numpy:numpy.dtype>` (this includes
+      :class:`~numpy:numpy.dtype` objects), or a strategy that generates such
       values.
     * ``shape`` may be an integer >= 0, a tuple of length >= 0 of such
       integers, or a strategy that generates such values.
@@ -305,13 +305,13 @@ def arrays(
     * ``fill`` is a strategy that may be used to generate a single background
       value for the array. If None, a suitable default will be inferred
       based on the other arguments. If set to
-      :func:`st.nothing() <hypothesis.strategies.nothing>` then filling
+      :func:`~hypothesis.strategies.nothing` then filling
       behaviour will be disabled entirely and every element will be generated
       independently.
     * ``unique`` specifies if the elements of the array should all be
       distinct from one another. Note that in this case multiple NaN values
       may still be allowed. If fill is also set, the only valid values for
-      it to return are NaN values (anything for which :func:`numpy.isnan`
+      it to return are NaN values (anything for which :obj:`numpy:numpy.isnan`
       returns True. So e.g. for complex numbers (nan+1j) is also a valid fill).
       Note that if unique is set to True the generated values must be hashable.
 

hypothesis-python/src/hypothesis/strategies.py

@@ -869,7 +869,7 @@ def characters(
       exception.
 
     The ``_codepoint`` arguments must be integers between zero and
-    :obj:`python:sys.max_unicode`.  The ``_characters`` arguments must be
+    :obj:`python:sys.maxunicode`.  The ``_characters`` arguments must be
     collections of length-one unicode strings, such as a unicode string.
 
     The ``_categories`` arguments must be used to specify either the
@@ -1004,14 +1004,14 @@ def text(
 def from_regex(regex, fullmatch=False):
     # type: (Union[AnyStr, Pattern[AnyStr]], bool) -> SearchStrategy[AnyStr]
     """Generates strings that contain a match for the given regex (i.e. ones
-    for which :func:`re.search` will return a non-None result).
+    for which :func:`python:re.search` will return a non-None result).
 
     ``regex`` may be a pattern or :func:`compiled regex <python:re.compile>`.
     Both byte-strings and unicode strings are supported, and will generate
     examples of the same type.
 
-    You can use regex flags such as :const:`re.IGNORECASE`, :const:`re.DOTALL`
-    or :const:`re.UNICODE` to control generation. Flags can be passed either
+    You can use regex flags such as :obj:`python:re.IGNORECASE` or
+    :obj:`python:re.DOTALL` to control generation. Flags can be passed either
     in compiled regex or inside the pattern with a ``(?iLmsux)`` group.
 
     Some regular expressions are only partly supported - the underlying
@@ -1463,7 +1463,7 @@ def decimals(
     places=None,  # type: int
 ):
     # type: (...) -> SearchStrategy[Decimal]
-    """Generates instances of :class:`decimals.Decimal`, which may be:
+    """Generates instances of :class:`python:decimal.Decimal`, which may be:
 
     - A finite rational number, between ``min_value`` and ``max_value``.
     - Not a Number, if ``allow_nan`` is True.  None means "allow NaN, unless

requirements/tools.txt

@@ -75,7 +75,7 @@ six==1.11.0               # via bandit, dparse, mock, more-itertools, packaging,
 smmap2==2.0.4             # via gitdb2
 snowballstemmer==1.2.1    # via pydocstyle, sphinx
 sphinx-rtd-theme==0.4.1
-sphinx==1.7.9
+sphinx==1.8.0
 sphinxcontrib-websupport==1.1.0  # via sphinx
 stevedore==1.29.0         # via bandit
 toml==0.9.6

tooling/src/hypothesistooling/__main__.py

@@ -341,8 +341,9 @@ def documentation():
         if hp.has_release():
             hp.update_changelog_and_version()
         pip_tool(
-            'sphinx-build', '-W', '-b', 'html', '-d', 'docs/_build/doctrees',
-            'docs', 'docs/_build/html'
+            # See http://www.sphinx-doc.org/en/stable/man/sphinx-build.html
+            'sphinx-build', '-n', '-W', '--keep-going', '-T', '-E',
+            '-b', 'html', 'docs', 'docs/_build/html'
         )
     finally:
         subprocess.check_call([

whole-repo-tests/test_rst_is_valid.py

@@ -18,7 +18,6 @@
 from __future__ import division, print_function, absolute_import
 
 import os
-import subprocess
 
 import hypothesistooling as tools
 import hypothesistooling.projects.hypothesispython as hp
@@ -42,18 +41,3 @@ def test_passes_rst_lint():
 
 def test_passes_flake8():
     pip_tool('flake8', '--select=W191,W291,W292,W293,W391', *ALL_RST)
-
-
-def test_crossref_type():
-    """Checks for a common typo in Sphinx cross-references.
-
-    This greps for things that look like the start of a cross-reference:
-    backtick, maybe tilde, and (incorrectly!) the plural form of
-    hypothesis. We assert that the exit code is non-zero (i.e. no
-    matches found), and run the command across the whole Python
-    directory to catch docs, docstrings, and even RELEASE.rst if
-    present.
-    """
-    assert subprocess.call([
-        'git', 'grep', '--line-number', '--perl-regexp', '`~?hypotheses'
-    ], cwd=hp.HYPOTHESIS_PYTHON)