docs: add hoverxref & codeautolink support. Various fixes

[kachida]

Fixes #1522

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

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:

#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:

trio/docs/source/reference-core.rst

Lines 252 to 258 in 96a5524

	In the simplest case, you can apply a timeout to a block of code::
	with trio.move_on_after(30):
	result = await do_http_get("https://...")
	print("result is", result)
	print("with block finished")

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]

The vast majority of the diff is near identical, so I pointed out most points where anything is different.

[jakkdl]

random typo I noticed when searching for ::$

[jakkdl]

and a second instance of invalid python syntax

[jakkdl]

pycon is "python console"

[jakkdl]

I don't think there is any language highlighting that's relevant here, so made it a generic code block.

[jakkdl]

shell

[jakkdl]

there might be some windows console identifier, but I just made it sh /shrug

[jakkdl]

most of the code uses trio.xxxx, maybe even all of it, but not much reason not to keep from trio import *. Although it's plausible we should also import testing/lowlevel/etc, have not scoured the docs that thoroughly yet.

[jakkdl]

Don't know why this raised errors, or by what, but it gave

/home/h/Git/trio/docs/source/reference-lowlevel.rst: WARNING: Could not match transformation of `asyncio` on source lines 1-1

[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.