From c302f0059f34e2c16a325fa09b5def6872dc32c8 Mon Sep 17 00:00:00 2001 From: Zac Hatfield-Dodds Date: Wed, 31 Jan 2024 18:50:32 +1100 Subject: [PATCH] update sphinx config --- hypothesis-python/RELEASE.rst | 3 +++ .../docs/_static/better-signatures.css | 25 +++++++++++++++++++ hypothesis-python/docs/changes.rst | 6 ++--- hypothesis-python/docs/conf.py | 10 +++++++- hypothesis-python/docs/settings.rst | 2 +- hypothesis-python/src/hypothesis/database.py | 8 +++--- .../src/hypothesis/extra/ghostwriter.py | 2 +- .../hypothesis/strategies/_internal/core.py | 4 ++- .../projects/hypothesispython.py | 1 - 9 files changed, 49 insertions(+), 12 deletions(-) create mode 100644 hypothesis-python/RELEASE.rst create mode 100644 hypothesis-python/docs/_static/better-signatures.css diff --git a/hypothesis-python/RELEASE.rst b/hypothesis-python/RELEASE.rst new file mode 100644 index 0000000000..8d323b1420 --- /dev/null +++ b/hypothesis-python/RELEASE.rst @@ -0,0 +1,3 @@ +RELEASE_TYPE: patch + +This patch improves formatting and adds some cross-references to our docs. diff --git a/hypothesis-python/docs/_static/better-signatures.css b/hypothesis-python/docs/_static/better-signatures.css new file mode 100644 index 0000000000..d23d38ea44 --- /dev/null +++ b/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; +} diff --git a/hypothesis-python/docs/changes.rst b/hypothesis-python/docs/changes.rst index f85b450845..a18af2e4d8 100644 --- a/hypothesis-python/docs/changes.rst +++ b/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) ` -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: diff --git a/hypothesis-python/docs/conf.py b/hypothesis-python/docs/conf.py index 8b7624f6fe..ba605b465c 100644 --- a/hypothesis-python/docs/conf.py +++ b/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" diff --git a/hypothesis-python/docs/settings.rst b/hypothesis-python/docs/settings.rst index f578d7f3a6..5b2db744fb 100644 --- a/hypothesis-python/docs/settings.rst +++ b/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 diff --git a/hypothesis-python/src/hypothesis/database.py b/hypothesis-python/src/hypothesis/database.py index 9fbdd31597..b53e8b8d5f 100644 --- a/hypothesis-python/src/hypothesis/database.py +++ b/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 `_. - 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__( diff --git a/hypothesis-python/src/hypothesis/extra/ghostwriter.py b/hypothesis-python/src/hypothesis/extra/ghostwriter.py index fde70caf75..68e6a85c29 100644 --- a/hypothesis-python/src/hypothesis/extra/ghostwriter.py +++ b/hypothesis-python/src/hypothesis/extra/ghostwriter.py @@ -1610,7 +1610,7 @@ def binary_operation( While :wikipedia:`binary operations ` 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 `, ``f(a, f(b, c)) == f(f(a, b), c)`` diff --git a/hypothesis-python/src/hypothesis/strategies/_internal/core.py b/hypothesis-python/src/hypothesis/strategies/_internal/core.py index 800a8c4e56..234b8de822 100644 --- a/hypothesis-python/src/hypothesis/strategies/_internal/core.py +++ b/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() diff --git a/tooling/src/hypothesistooling/projects/hypothesispython.py b/tooling/src/hypothesistooling/projects/hypothesispython.py index f04965b5e9..ae55c73aa7 100644 --- a/tooling/src/hypothesistooling/projects/hypothesispython.py +++ b/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",