Skip to content

Commit

Permalink
Merge pull request #3868 from Zac-HD/more-sphinx-options
Browse files Browse the repository at this point in the history
Update some Sphinx config for docs
  • Loading branch information
Zac-HD authored Jan 31, 2024
2 parents 0bd379c + c302f00 commit da350a7
Show file tree
Hide file tree
Showing 9 changed files with 49 additions and 12 deletions.
3 changes: 3 additions & 0 deletions hypothesis-python/RELEASE.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
RELEASE_TYPE: patch

This patch improves formatting and adds some cross-references to our docs.
25 changes: 25 additions & 0 deletions hypothesis-python/docs/_static/better-signatures.css
Original file line number Diff line number Diff line change
@@ -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;
}
6 changes: 3 additions & 3 deletions hypothesis-python/docs/changes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7269,7 +7269,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.

Expand Down Expand Up @@ -7601,7 +7601,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.

Expand Down Expand Up @@ -8066,7 +8066,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:

Expand Down
10 changes: 9 additions & 1 deletion hypothesis-python/docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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",
Expand Down Expand Up @@ -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"]
Expand Down Expand Up @@ -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"

Expand Down
2 changes: 1 addition & 1 deletion hypothesis-python/docs/settings.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions hypothesis-python/src/hypothesis/database.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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__(
Expand Down
2 changes: 1 addition & 1 deletion hypothesis-python/src/hypothesis/extra/ghostwriter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)``
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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(...)"

Expand Down Expand Up @@ -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()

Expand Down
1 change: 0 additions & 1 deletion tooling/src/hypothesistooling/projects/hypothesispython.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down

0 comments on commit da350a7

Please sign in to comment.