Add the sphinx-codeautolink extension

Author: cmarqu

Doc/_static/custom.css

@@ -0,0 +1,18 @@
+/*
+Style autolinks to reference documentation
+(https://sphinx-codeautolink.readthedocs.io/en/latest/examples.html#custom-link-styles)
+*/
+/*
+.sphinx-codeautolink-a {
+    text-decoration: none !important;
+}
+*/
+
+/* better for debugging */
+.sphinx-codeautolink-a {
+    text-decoration-style: solid !important;
+    text-decoration-color: #aaa;
+}
+.sphinx-codeautolink-a:hover {
+    text-decoration-color: black;
+}

Doc/conf.py

@@ -38,6 +38,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
     'sphinx.ext.extlinks',
+    'sphinx_codeautolink',
 ]
 
 # Skip if downstream redistributors haven't installed them
@@ -404,6 +405,9 @@
 # Additional static files.
 html_static_path = ['_static', 'tools/static']
 
+# Additional CSS files.
+html_css_files = ["custom.css"]
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'python' + release.replace('.', '')
 
@@ -413,6 +417,16 @@
 # Split pot files one per reST file
 gettext_compact = False
 
+# Options for automatic links from code examples to reference docs
+# (https://sphinx-codeautolink.readthedocs.io/)
+codeautolink_warn_on_missing_inventory = False
+codeautolink_warn_on_failed_resolve = False
+codeautolink_custom_blocks = {
+    # https://sphinx-codeautolink.readthedocs.io/en/latest/examples.html#doctest-code-blocks
+    "pycon3": "sphinx_codeautolink.clean_pycon",
+}
+# suppress_warnings = ["codeautolink"]
+
 # Options for LaTeX output
 # ------------------------
 

Doc/howto/regex.rst

@@ -19,6 +19,7 @@
    with the :mod:`re` module.  It provides a gentler introduction than the
    corresponding section in the Library Reference.
 
+.. highlight:: pycon
 
 Introduction
 ============

Doc/library/asyncio-stream.rst

@@ -538,13 +538,17 @@ Simple example querying HTTP headers of the URL passed on the command line::
     asyncio.run(print_http_headers(url))
 
 
-Usage::
+Usage:
 
-    python example.py http://example.com/path/page.html
+.. code-block:: shell
 
-or with HTTPS::
+   python example.py http://example.com/path/page.html
 
-    python example.py https://example.com/path/page.html
+or with HTTPS:
+
+.. code-block:: shell
+
+   python example.py https://example.com/path/page.html
 
 
 .. _asyncio_example_create_connection-streams:

Doc/library/asyncio-sync.rst

@@ -52,6 +52,7 @@ Lock
        # ... later
        async with lock:
            # access shared state
+           ...
 
    which is equivalent to::
 
@@ -61,6 +62,7 @@ Lock
        await lock.acquire()
        try:
            # access shared state
+           ...
        finally:
            lock.release()
 
@@ -305,6 +307,7 @@ Semaphore
        # ... later
        async with sem:
            # work with shared resource
+           ...
 
    which is equivalent to::
 
@@ -314,6 +317,7 @@ Semaphore
        await sem.acquire()
        try:
            # work with shared resource
+           ...
        finally:
            sem.release()
 
@@ -397,7 +401,9 @@ Barrier
 
       asyncio.run(example_barrier())
 
-   Result of this example is::
+   Result of this example is:
+
+   .. code-block:: none
 
       <asyncio.locks.Barrier object at 0x... [filling, waiters:2/3]>
       <asyncio.locks.Barrier object at 0x... [draining, waiters:0/3]>

Doc/requirements.txt

@@ -13,6 +13,7 @@ blurb
 
 sphinxext-opengraph~=0.10.0
 sphinx-notfound-page~=1.0.0
+sphinx-codeautolink~=0.16.0
 
 # The theme used by the documentation is stored separately, so we need
 # to install that as well.