update sphinx config

Author: Zac-HD

hypothesis-python/RELEASE.rst

@@ -0,0 +1,3 @@
+RELEASE_TYPE: patch
+
+This patch improves formatting and adds some cross-references to our docs.

hypothesis-python/docs/_static/better-signatures.css

@@ -0,0 +1,25 @@
+/* don't use italics for param names; looks bad with "|" for unions */
+.rst-content dl .sig-param {
+  font-style: normal;
+}
+
+/* Take out pointless vertical whitespace in the signatures.
+ * See also https://github.com/readthedocs/sphinx_rtd_theme/pull/1450 */
+.rst-content dl .sig dl,
+.rst-content dl .sig dd {
+  margin-bottom: 0;
+}
+
+/* Make signature boxes full-width, with view-source and header links right-aligned. */
+.rst-content dl .sig {
+  width: -webkit-fill-available;
+}
+.rst-content .viewcode-link {
+  display: inline-flex;
+  float: inline-end;
+  margin-right: 1.5em;
+}
+.rst-content .headerlink {
+  position: absolute;
+  right: 0.5em;
+}

hypothesis-python/docs/changes.rst

@@ -7261,7 +7261,7 @@ This release makes it an explicit error to call
 as there are no possible values that can be generated (:issue:`1859`).
 
 :func:`floats(min_value=0.0, max_value=-0.0) <hypothesis.strategies.floats>`
-is now deprecated.  While `0. == -0.` and we could thus generate either if
+is now deprecated.  While ``0. == -0.`` and we could thus generate either if
 comparing by value, violating the sequence ordering of floats is a special
 case we don't want or need.
 
@@ -7593,7 +7593,7 @@ one.  These shapes are rare and have some odd behavior, but are particularly
 important to test for just that reason!
 
 In a related bigfix, :func:`~hypothesis.extra.numpy.arrays` now supports generating
-zero-dimensional arrays with `dtype=object` and a strategy for iterable elements.
+zero-dimensional arrays with ``dtype=object`` and a strategy for iterable elements.
 Previously, the array element would incorrectly be set to the first item in the
 generated iterable.
 
@@ -8058,7 +8058,7 @@ This release has no user visible changes but updates our URLs to use HTTPS.
 -------------------
 
 Hypothesis can now automatically generate values for Django models with a
-`URLfield`, thanks to a new provisional strategy for URLs (:issue:`1388`).
+`~django.db.models.URLField`, thanks to a new provisional strategy for URLs (:issue:`1388`).
 
 .. _v3.86.6:
 

hypothesis-python/docs/conf.py

@@ -9,6 +9,7 @@
 # obtain one at https://mozilla.org/MPL/2.0/.
 
 import datetime
+import re
 import sys
 import types
 from pathlib import Path
@@ -18,9 +19,15 @@
 root = Path(__file__).parent.parent
 sys.path.append(str(root / "src"))
 
+needs_sphinx = re.search(
+    r"sphinx==([0-9\.]+)", root.joinpath("../requirements/tools.txt").read_text()
+).group(1)
+default_role = "py:obj"
+nitpicky = True
 
 autodoc_member_order = "bysource"
 autodoc_typehints = "none"
+maximum_signature_line_length = 60  # either one line, or one param per line
 
 extensions = [
     "sphinx.ext.autodoc",
@@ -113,6 +120,7 @@ def setup(app):
     "attrs": ("https://www.attrs.org/en/stable/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
     "IPython": ("https://ipython.readthedocs.io/en/stable/", None),
+    "lark": ("https://lark-parser.readthedocs.io/en/stable/", None),
 }
 
 autodoc_mock_imports = ["numpy", "pandas", "redis", "django", "pytz"]
@@ -148,7 +156,7 @@ def setup(app):
 
 html_static_path = ["_static"]
 
-html_css_files = ["wrap-in-tables.css"]
+html_css_files = ["better-signatures.css", "wrap-in-tables.css"]
 
 htmlhelp_basename = "Hypothesisdoc"
 

hypothesis-python/docs/settings.rst

@@ -230,7 +230,7 @@ specific tests.
 
 Optionally, you may define the environment variable to load a profile for you.
 This is the suggested pattern for running your tests on CI.
-The code below should run in a `conftest.py` or any setup/initialization section of your test suite.
+The code below should run in a ``conftest.py`` or any setup/initialization section of your test suite.
 If this variable is not defined the Hypothesis defined defaults will be loaded.
 
 .. code-block:: pycon

hypothesis-python/src/hypothesis/database.py

@@ -349,8 +349,8 @@ class GitHubArtifactDatabase(ExampleDatabase):
         You must provide ``GITHUB_TOKEN`` as an environment variable. In CI, Github Actions provides
         this automatically, but it needs to be set manually for local usage. In a developer machine,
         this would usually be a `Personal Access Token <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>`_.
-        If the repository is private, it's necessary for the token to have `repo` scope
-        in the case of a classic token, or `actions:read` in the case of a fine-grained token.
+        If the repository is private, it's necessary for the token to have ``repo`` scope
+        in the case of a classic token, or ``actions:read`` in the case of a fine-grained token.
 
 
     In most cases, this will be used
@@ -400,9 +400,9 @@ class GitHubArtifactDatabase(ExampleDatabase):
     does not support downloading artifacts from previous workflow runs.
 
     The database automatically implements a simple file-based cache with a default expiration period
-    of 1 day. You can adjust this through the `cache_timeout` property.
+    of 1 day. You can adjust this through the ``cache_timeout`` property.
 
-    For mono-repo support, you can provide a unique `artifact_name` (e.g. `hypofuzz-example-db-frontend`).
+    For mono-repo support, you can provide a unique ``artifact_name`` (e.g. ``hypofuzz-example-db-frontend``).
     """
 
     def __init__(

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

@@ -1610,7 +1610,7 @@ def binary_operation(
 
     While :wikipedia:`binary operations <Binary_operation>` are not particularly
     common, they have such nice properties to test that it seems a shame not to
-    demonstrate them with a ghostwriter.  For an operator `f`, test that:
+    demonstrate them with a ghostwriter.  For an operator ``f``, test that:
 
     - if :wikipedia:`associative <Associative_property>`,
       ``f(a, f(b, c)) == f(f(a, b), c)``

hypothesis-python/src/hypothesis/strategies/_internal/core.py

@@ -2124,6 +2124,8 @@ def __init__(self, data):
         self.count = 0
         self.conjecture_data = data
 
+    __signature__ = Signature()  # hide internals from Sphinx introspection
+
     def __repr__(self):
         return "data(...)"
 
@@ -2182,7 +2184,7 @@ def data() -> SearchStrategy[DataObject]:
     complete information.
 
     Examples from this strategy do not shrink (because there is only one),
-    but the result of calls to each draw() call shrink as they normally would.
+    but the result of calls to each ``data.draw()`` call shrink as they normally would.
     """
     return DataStrategy()
 

tooling/src/hypothesistooling/projects/hypothesispython.py

@@ -65,7 +65,6 @@ def build_docs(builder="html"):
     # (unfortunately most options only have the short flag version)
     tools.scripts.pip_tool(
         "sphinx-build",
-        "-n",
         "-W",
         "--keep-going",
         "-T",