Add new Sphinx configuration options

[Zac-HD]

From this page on Sphinx configuration options, I think there are some new ones we should try out:

• nitpicky = True to warn about more missing references. Also set the default_role to py:obj, which will ensure the most common cases work out after all. (main effect: CI will now warn when people use single instead of double-backticks for monospace)
• needs_sphinx - dynamically load this from requirements/tools.txt so it stays up-to-date with our pins? We install from pins on readthedocs so this should work fine. Convert the == to >= so that checking out an old branch doesn't force a downgrade to build docs.
• enable maximum_signature_line_length and python_... - going to one argument per line will enable us to show type annotations again (changing autodoc_typehints from none to signature); we'll also want to set autodoc_type_aliases and perhaps load this dynamically from the source code (matching on _: TypeAlias = _ lines - actually this would be a great feature to upstream!)

[Zac-HD]

Ooooh boy, getting nice docs for type annotations is going to be harder than I'd hoped.

• maximum_signature_line_length makes signatures pretty ugly via Sphinx7 multiline signatures contain very wide line spacing that is not changeable. readthedocs/sphinx_rtd_theme#1529 / Fix margins between <dt> and <dl> readthedocs/sphinx_rtd_theme#1450.
  • I'd also want the blue shading to span the column, like an .. info:: box, rather than stopping at the signature width.
  • Both might be fixable with custom CSS downstream?
• autodoc_type_aliases only works with from __future__ import annotations... i.e. PEP-563, which in Python 3.13 will be replaced by PEP-649. In any case, this is pretty painful - we'll want to have some way of post-processing the annotation strings and that'll probably need a custom Sphinx plugin (though not a huge one)
• The type annotations get autolinked, which is fine, but then nitpicky mode complains that the type annotations aren't documented and this is pretty annoying.
  • Fortunately we can break out nitpick_ignore = [...] for whatever we don't want to document, such as typevars
  • There are also a few strings which just seem to be resolution errors.
• maybe https://github.com/tox-dev/sphinx-autodoc-typehints would be helpful, going to see if I can get away without it first

[Zac-HD]

OK, I'm just going to abandon the type-annotations part because I'm not sure whether it's net-positive for readers, and want to ship the rest of the stuff above quickly. If we revisit in future, you can jumpstart with:

 autodoc_member_order = "bysource"
-autodoc_typehints = "none"
+autodoc_typehints = "signature"
 maximum_signature_line_length = 60  # either one line, or one param per line
 
+nitpick_ignore = [
+    # CPython docs limitations
+    ("py:class", "module"),
+    ("py:class", "ellipsis"),
+    # TypeVars we don't want to document
+    ("py:class", "P"),
+    ("py:class", "hypothesis.core.TestFunc"),
+    ("py:class", "hypothesis.extra.array_api.DataType"),
+    ("py:class", "hypothesis.extra.django._fields.F"),
+    ("py:class", "hypothesis.extra.django._impl.ModelT"),
+    ("py:class", "hypothesis.extra.ghostwriter.X"),
+    ("py:class", "hypothesis.extra.ghostwriter.Y"),
+    ("py:class", "hypothesis.extra.numpy.D"),
+    ("py:class", "hypothesis.strategies._internal.strategies.Ex"),
+    ("py:class", "hypothesis.strategies._internal.strategies.Ex_Inv"),
+    ("py:class", "hypothesis.strategies._internal.strategies.T"),
+    # Other internal classes we don't want to document
+    ("py:class", "Verbosity"),
+    ("py:class", "hypothesis.extra._array_helpers.BroadcastableShapes"),
+    ("py:class", "hypothesis.stateful.Bundle"),
+    ("py:class", "hypothesis.stateful.MultipleResults"),
+    ("py:class", "hypothesis.stateful._OmittedArgument"),
+    ("py:class", "hypothesis.strategies._internal.core.RandomSeeder"),
+    ("py:class", "hypothesis.utils.conventions.UniqueIdentifier"),
+    # Random other issues
+    ("py:class", "hypothesis.strategies.SearchStrategy[numpy.typing.NDArray.~D]"),
+    (
+        "py:class",
+        "hypothesis.strategies.SearchStrategy[~typing.Tuple[numpy.typing.NDArray.~D, ...]]",
+    ),
+]