docs: add hoverxref & codeautolink support. Various fixes

docs-requirements.in

@@ -6,6 +6,8 @@ sphinx_rtd_theme
 sphinxcontrib-jquery
 sphinxcontrib-trio
 towncrier
+sphinx-hoverxref
+sphinx-codeautolink
 
 # Trio's own dependencies
 cffi; os_name == "nt"

docs-requirements.txt

@@ -12,6 +12,8 @@ attrs==23.2.0
     #   outcome
 babel==2.14.0
     # via sphinx
+beautifulsoup4==4.12.3
+    # via sphinx-codeautolink
 certifi==2024.2.2
     # via requests
 cffi==1.16.0
@@ -69,12 +71,20 @@ snowballstemmer==2.2.0
     # via sphinx
 sortedcontainers==2.4.0
     # via -r docs-requirements.in
+soupsieve==2.5
+    # via beautifulsoup4
 sphinx==7.1.2
     # via
     #   -r docs-requirements.in
+    #   sphinx-codeautolink
+    #   sphinx-hoverxref
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
     #   sphinxcontrib-trio
+sphinx-codeautolink==0.15.0
+    # via -r docs-requirements.in
+sphinx-hoverxref==1.3.0
+    # via -r docs-requirements.in
 sphinx-rtd-theme==2.0.0
     # via -r docs-requirements.in
 sphinxcontrib-applehelp==1.0.4
@@ -86,6 +96,7 @@ sphinxcontrib-htmlhelp==2.0.1
 sphinxcontrib-jquery==4.1
     # via
     #   -r docs-requirements.in
+    #   sphinx-hoverxref
     #   sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx

docs/source/conf.py

@@ -150,6 +150,8 @@ def setup(app: Sphinx) -> None:
     "sphinx.ext.napoleon",
     "sphinxcontrib_trio",
     "sphinxcontrib.jquery",
+    "hoverxref.extension",
+    "sphinx_codeautolink",
     "local_customization",
     "typevars",
 ]
@@ -162,6 +164,31 @@ def setup(app: Sphinx) -> None:
     "trio-util": ("https://trio-util.readthedocs.io/en/latest/", None),
 }
 
+# See https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html
+hoverxref_auto_ref = True
+hoverxref_domains = ["py"]
+# Set the default style (tooltip) for all types to silence logging.
+# See https://github.com/readthedocs/sphinx-hoverxref/issues/211
+hoverxref_role_types = {
+    "attr": "tooltip",
+    "class": "tooltip",
+    "const": "tooltip",
+    "exc": "tooltip",
+    "func": "tooltip",
+    "meth": "tooltip",
+    "mod": "tooltip",
+    "obj": "tooltip",
+    "ref": "tooltip",
+    "data": "tooltip",
+}
+
+# See https://sphinx-codeautolink.readthedocs.io/en/latest/reference.html#configuration
+codeautolink_autodoc_inject = False
+codeautolink_global_preface = """
+import trio
+from trio import *
+"""
+
 
 def add_intersphinx(app: Sphinx) -> None:
     """Add some specific intersphinx mappings.

docs/source/contributing.rst

@@ -199,8 +199,12 @@ you'll have a chance to see and fix any remaining issues then.
 Every change should have 100% coverage for both code and tests. But,
 you can use ``# pragma: no cover`` to mark lines where
 lack-of-coverage isn't something that we'd want to fix (as opposed to
-it being merely hard to fix). For example::
+it being merely hard to fix). For example:
 
+.. code-block:: python
+
+    if ...:
+        ...
     else:  # pragma: no cover
         raise AssertionError("this can't happen!")
 
@@ -289,7 +293,9 @@ Instead of wasting time arguing about code formatting, we use `black
 <https://github.com/psf/black>`__ as well as other tools to automatically
 format all our code to a standard style. While you're editing code you
 can be as sloppy as you like about whitespace; and then before you commit,
-just run::
+just run:
+
+.. code-block::
 
     pip install -U pre-commit
     pre-commit
@@ -301,20 +307,26 @@ names, writing useful comments, and making sure your docstrings are
 nicely formatted. (black doesn't reformat comments or docstrings.)
 
 If you would like, you can even have pre-commit run before you commit by
-running::
+running:
+
+.. code-block::
 
     pre-commit install
 
 and now pre-commit will run before git commits. You can uninstall the
-pre-commit hook at any time by running::
+pre-commit hook at any time by running:
+
+.. code-block::
 
     pre-commit uninstall
 
 
 Very occasionally, you'll want to override black formatting. To do so,
 you can can add ``# fmt: off`` and ``# fmt: on`` comments.
 
-If you want to see what changes black will make, you can use::
+If you want to see what changes black will make, you can use:
+
+.. code-block::
 
     black --diff trio
 
@@ -396,7 +408,9 @@ whitelist in ``docs/source/conf.py``.
 To build the docs locally, use our handy ``docs-requirements.txt``
 file to install all of the required packages (possibly using a
 virtualenv). After that, build the docs using ``make html`` in the
-docs directory. The whole process might look something like this::
+docs directory. The whole process might look something like this:
+
+.. code-block::
 
     cd path/to/project/checkout/
     pip install -r docs-requirements.txt

docs/source/design.rst

@@ -312,7 +312,9 @@ mean.
 This is often a challenging rule to follow – for example, the call
 soon code has to jump through some hoops to make it happen – but its
 most dramatic influence can seen in Trio's task-spawning interface,
-where it motivates the use of "nurseries"::
+where it motivates the use of "nurseries":
+
+.. code-block:: python
 
    async def parent():
        async with trio.open_nursery() as nursery:
@@ -376,18 +378,22 @@ Specific style guidelines
   unconditionally act as cancel+schedule points.
 
 * Any function that takes a callable to run should have a signature
-  like::
+  like:
+
+  .. code-block:: python
 
-     def call_the_thing(fn, *args, kwonly1, kwonly2, ...)::
+     def call_the_thing(fn, *args, kwonly1, kwonly2):
          ...
 
   where ``fn(*args)`` is the thing to be called, and ``kwonly1``,
-  ``kwonly2``, ... are keyword-only arguments that belong to
+  ``kwonly2``, are keyword-only arguments that belong to
   ``call_the_thing``. This applies even if ``call_the_thing`` doesn't
   take any arguments of its own, i.e. in this case its signature looks
-  like::
+  like:
 
-     def call_the_thing(fn, *args)::
+  .. code-block:: python
+
+     def call_the_thing(fn, *args):
          ...
 
   This allows users to skip faffing about with
@@ -410,12 +416,14 @@ Specific style guidelines
   worse, and you get used to the convention pretty quick.
 
 * If it's desirable to have both blocking and non-blocking versions of
-  a function, then they look like::
+  a function, then they look like:
+
+  .. code-block:: python
 
-     async def OPERATION(...):
+     async def OPERATION(arg1, arg2):
          ...
 
-     def OPERATION_nowait(...):
+     def OPERATION_nowait(arg1, arg2):
          ...
 
   and the ``nowait`` version raises :exc:`trio.WouldBlock` if it would block.

docs/source/history.rst

@@ -1248,7 +1248,9 @@ Highlights
 * The new nursery :meth:`~Nursery.start` method makes it
   easy to perform controlled start-up of long-running tasks. For
   example, given an appropriate ``http_server_on_random_open_port``
-  function, you could write::
+  function, you could write:
+
+  .. code-block:: python
 
       port = await nursery.start(http_server_on_random_open_port)
 
@@ -1490,7 +1492,9 @@ Other changes
   functions, if you're using asyncio you have to use asyncio
   functions, and so forth. (See the discussion of the "async sandwich"
   in the Trio tutorial for more details.) So for example, this isn't
-  going to work::
+  going to work:
+
+  .. code-block:: python
 
       async def main():
           # asyncio here