docs: add hoverxref & codeautolink support. Various fixes

[kachida]

Fixes #1522

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.61%. Comparing base (1bb98ae) to head (f0cb052).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2968      +/-   ##
==========================================
- Coverage   99.63%   99.61%   -0.02%     
==========================================
  Files         117      117              
  Lines       17593    17593              
  Branches     3173     3173              
==========================================
- Hits        17528    17525       -3     
- Misses         46       47       +1     
- Partials       19       21       +2     

see 1 file with indirect coverage changes

[kachida]

Related issue:

https://github.com/python-trio/trio/issues/1522

[jakkdl]

~~Read the Docs build is failing (as can be seen by clicking through from the checks for the PR):~~ updated doc-requirements.in and .txt

[jakkdl]

The hoverxref seems to be working excellently, but objects in examples don't seem to be clickable (i.e. the codeautolink part)? https://trio--2968.org.readthedocs.build/en/2968/reference-testing.html

[kachida]

Thank you, @jakkdl, for adding the missing dependencies in the requirements file. I will review and confirm with you why the objects do not appear clickable.

[jakkdl]

It appears that codeautolink requires explicitly marking code blocks as python code blocks, so this does not work: https://github.com/python-trio/trio/blob/96a5524cb1e5b4f5997f8e5638b97b145ed254de/docs/source/reference-core.rst?plain=1#L252-L258

But this does (after adding import trio to codeautolink_global_preface)

In the simplest case, you can apply a timeout to a block of code:

.. code:: python

   with trio.move_on_after(30):
       result = await do_http_get("https://...")
       print("result is", result)
   print("with block finished")

Skimming configuration and examples I don't find a way to configure the former to work, so will have to replace the syntax of all code blocks - but shouldn't be too bad with a regex search&replace.

This does also add syntax highlighting in my editor, and in viewing the source on github.

[jakkdl]

I noticed one file using

.. code-block:: python3


  if bool(int('5')):
      print("hello world")

Turns out github (or my editor) don't recognize python3 as a language directive for highlighting the rst source code

.. code-block:: python

  if bool(int('5')):
      print("hello world")

(No clue why, it works in normal code blocks, and is a valid identifier both according to linguist (used for GH code blocks) and pygments (used by RST))

After an unreasonable amount of digging I've finally figured out the difference between .. code:: and .. code-block::. Sphinx does not seem to document the existence of .. code:: at all, or mention it as an option for showing code, and you have to dig deep to find the docutils documentation for directives to find it documented. Sphinx seems to treat them identically in ~all cases, only diverging if you want to use options for code-block. So it seems like the reasonable default is to stick to .. code-block:: in case anybody want to add any options to a block in the future.

A trailing :: is a literal block (sphinx) / preformatted block (docutils), where python highlighting was set with highlight_language.