bpo-33649: Add low-level APIs index. (GH-9364)

10 files changed, 571 insertions, 31 deletions

diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst
index dc69100..d5b5659 100644
--- a/Doc/library/asyncio-api-index.rst
+++ b/Doc/library/asyncio-api-index.rst
@@ -1,9 +1,9 @@
 .. currentmodule:: asyncio
 
 
-=====================
-High-level APIs Index
-=====================
+====================
+High-level API Index
+====================
 
 This page lists all high-level async/await enabled asyncio APIs.
 
@@ -16,6 +16,7 @@ await on multiple things with timeouts.
 
 .. list-table::
     :widths: 50 50
+    :class: full-width-table
 
     * - :func:`run`
       - Create event loop, run a coroutine, close the loop.
@@ -36,7 +37,7 @@ await on multiple things with timeouts.
       - Shield from cancellation.
 
     * - ``await`` :func:`wait`
-      - Monitor for completeness.
+      - Monitor for completion.
 
     * - :func:`current_task`
       - Return the current Task.
@@ -47,6 +48,12 @@ await on multiple things with timeouts.
     * - :class:`Task`
       - Task object.
 
+    * - :func:`run_coroutine_threadsafe`
+      - Schedule a coroutine from another OS thread.
+
+    * - ``for in`` :func:`as_completed`
+      - Monitor for completion with a ``for`` loop.
+
 
 .. rubric:: Examples
 
@@ -72,6 +79,7 @@ implement connection pools, and pub/sub patterns.
 
 .. list-table::
     :widths: 50 50
+    :class: full-width-table
 
     * - :class:`Queue`
       - A FIFO queue.
@@ -98,6 +106,7 @@ Utilities to spawn subprocesses and run shell commands.
 
 .. list-table::
     :widths: 50 50
+    :class: full-width-table
 
     * - ``await`` :func:`create_subprocess_exec`
       - Create a subprocess.
@@ -121,6 +130,7 @@ High-level APIs to work with network IO.
 
 .. list-table::
     :widths: 50 50
+    :class: full-width-table
 
     * - ``await`` :func:`open_connection`
       -  Establish a TCP connection.
@@ -156,6 +166,7 @@ Threading-like synchronization primitives that can be used in Tasks.
 
 .. list-table::
     :widths: 50 50
+    :class: full-width-table
 
     * - :class:`Lock`
       - A mutex lock.
@@ -186,6 +197,7 @@ Exceptions
 
 .. list-table::
     :widths: 50 50
+    :class: full-width-table
 
 
     * - :exc:`asyncio.TimeoutError`
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 3e1571f..909d3ea3 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -980,7 +980,7 @@ Availability: UNIX.
 Executing code in thread or process pools
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. method:: loop.run_in_executor(executor, func, \*args)
+.. coroutinemethod:: loop.run_in_executor(executor, func, \*args)
 
    Arrange for a *func* to be called in the specified executor.
 
@@ -1418,7 +1418,7 @@ need to be written this way; consider using high-level functions
 like :func:`asyncio.run`.
 
 
-.. _asyncio-hello-world-callback:
+.. _asyncio_example_lowlevel_helloworld:
 
 Hello World with call_soon()
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1451,7 +1451,7 @@ event loop::
    example created with a coroutine and the :func:`run` function.
 
 
-.. _asyncio-date-callback:
+.. _asyncio_example_call_later:
 
 Display the current date with call_later()
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1488,7 +1488,7 @@ during 5 seconds, and then stops the event loop::
    created with a coroutine and the :func:`run` function.
 
 
-.. _asyncio-watch-read-event:
+.. _asyncio_example_watch_fd:
 
 Watch a file descriptor for read events
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1531,15 +1531,17 @@ Wait until a file descriptor received some data using the
 
 .. seealso::
 
-   * A similar :ref:`example <asyncio-register-socket>`
+   * A similar :ref:`example <asyncio_example_create_connection>`
      using transports, protocols, and the
      :meth:`loop.create_connection` method.
 
-   * Another similar :ref:`example <asyncio-register-socket-streams>`
+   * Another similar :ref:`example <asyncio_example_create_connection-streams>`
      using the high-level :func:`asyncio.open_connection` function
      and streams.
 
 
+.. _asyncio_example_unix_signals:
+
 Set signal handlers for SIGINT and SIGTERM
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst
index 19bf8a6..d6c5335 100644
--- a/Doc/library/asyncio-future.rst
+++ b/Doc/library/asyncio-future.rst
@@ -191,6 +191,8 @@ Future Object
       .. versionadded:: 3.7
 
 
+.. _asyncio_example_future:
+
 This example creates a Future object, creates and schedules an
 asynchronous Task to set result for the Future, and waits until
 the Future has a result::
diff --git a/Doc/library/asyncio-llapi-index.rst b/Doc/library/asyncio-llapi-index.rst
new file mode 100644
index 0000000..7fb1e60
--- /dev/null
+++ b/Doc/library/asyncio-llapi-index.rst
@@ -0,0 +1,510 @@
+.. currentmodule:: asyncio
+
+
+===================
+Low-level API Index
+===================
+
+This page lists all low-level asyncio APIs.
+
+
+Obtaining the Event Loop
+========================
+
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :func:`asyncio.get_running_loop`
+      - The **preferred** function to get the running event loop.
+
+    * - :func:`asyncio.get_event_loop`
+      - Get an event loop instance (current or via the policy).
+
+    * - :func:`asyncio.set_event_loop`
+      - Set the event loop as current via the current policy.
+
+    * - :func:`asyncio.new_event_loop`
+      - Create a new event loop.
+
+
+.. rubric:: Examples
+
+* :ref:`Using asyncio.get_running_loop() <asyncio_example_future>`.
+
+
+Event Loop Methods
+==================
+
+See also the main documentation section about the
+:ref:`event loop methods <asyncio-event-loop>`.
+
+.. rubric:: Lifecycle
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`loop.run_until_complete`
+      - Run a Future/Task/awaitable until complete.
+
+    * - :meth:`loop.run_forever`
+      - Run the event loop forever.
+
+    * - :meth:`loop.stop`
+      - Stop the event loop.
+
+    * - :meth:`loop.stop`
+      - Close the event loop.
+
+    * - :meth:`loop.is_running()`
+      - Return ``True`` if the event loop is running.
+
+    * - :meth:`loop.is_closed()`
+      - Return ``True`` if the event loop is closed.
+
+    * - ``await`` :meth:`loop.shutdown_asyncgens`
+      - Close asynchronous generators.
+
+
+.. rubric:: Debugging
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`loop.set_debug`
+      - Enable or disable the debug mode.
+
+    * - :meth:`loop.get_debug`
+      - Get the current debug mode.
+
+
+.. rubric:: Scheduling Callbacks
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`loop.call_soon`
+      - Invoke a callback soon.
+
+    * - :meth:`loop.call_soon_threadsafe`
+      - A thread-safe variant of :meth:`loop.call_soon`.
+
+    * - :meth:`loop.call_later`
+      - Invoke a callback *after* the given time.
+
+    * - :meth:`loop.call_at`
+      - Invoke a callback *at* the given time.
+
+
+.. rubric:: Thread/Process Pool
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``await`` :meth:`loop.run_in_executor`
+      - Run a CPU-bound or other blocking function in
+        a :mod:`concurrent.futures` executor.
+
+    * - :meth:`loop.set_default_executor`
+      - Set the default executor for :meth:`loop.run_in_executor`.
+
+
+.. rubric:: Tasks and Futures
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`loop.create_future`
+      - Create a :class:`Future` object.
+
+    * - :meth:`loop.create_task`
+      - Schedule coroutine as a :class:`Task`.
+
+    * - :meth:`loop.set_task_factory`
+      - Set a factory used by :meth:`loop.create_task` to
+        create :class:`Tasks <Task>`.
+
+    * - :meth:`loop.get_task_factory`
+      - Get the factory :meth:`loop.create_task` uses
+        to create :class:`Tasks <Task>`.
+
+
+.. rubric:: DNS
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``await`` :meth:`loop.getaddrinfo`
+      - Asynchronous version of :meth:`socket.getaddrinfo`.
+
+    * - ``await`` :meth:`loop.getnameinfo`
+      - Asynchronous version of :meth:`socket.getnameinfo`.
+
+
+.. rubric:: Networking and IPC
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``await`` :meth:`loop.create_connection`
+      - Open a TCP connection.
+
+    * - ``await`` :meth:`loop.create_server`
+      - Create a TCP server.
+
+    * - ``await`` :meth:`loop.create_unix_connection`
+      - Open a Unix socket connection.
+
+    * - ``await`` :meth:`loop.create_unix_server`
+      - Create a Unix socket server.
+
+    * - ``await`` :meth:`loop.connect_accepted_socket`
+      - Wrap a :class:`~socket.socket` into a ``(transport, protocol)``
+        pair.
+
+    * - ``await`` :meth:`loop.create_datagram_endpoint`
+      - Open a datagram (UDP) connection.
+
+    * - ``await`` :meth:`loop.sendfile`
+      - Send a file over a transport.
+
+    * - ``await`` :meth:`loop.start_tls`
+      - Upgrade an existing connection to TLS.
+
+    * - ``await`` :meth:`loop.connect_read_pipe`
+      - Wrap a read end of a pipe into a ``(transport, protocol)`` pair.
+
+    * - ``await`` :meth:`loop.connect_write_pipe`
+      - Wrap a write end of a pipe into a ``(transport, protocol)`` pair.
+
+
+.. rubric:: Sockets
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``await`` :meth:`loop.sock_recv`
+      - Receive data from the :class:`~socket.socket`.
+
+    * - ``await`` :meth:`loop.sock_recv_into`
+      - Receive data from the :class:`~socket.socket` into a buffer.
+
+    * - ``await`` :meth:`loop.sock_sendall`
+      - Send data to the :class:`~socket.socket`.
+
+    * - ``await`` :meth:`loop.sock_connect`
+      - Connect the :class:`~socket.socket`.
+
+    * - ``await`` :meth:`loop.sock_accept`
+      - Accept a :class:`~socket.socket` connection.
+
+    * - ``await`` :meth:`loop.sock_sendfile`
+      - Send a file over the :class:`~socket.socket`.
+
+    * - :meth:`loop.add_reader`
+      - Start watching a file descriptor for read availability.
+
+    * - :meth:`loop.remove_reader`
+      - Stop watching a file descriptor for read availability.
+
+    * - :meth:`loop.add_writer`
+      - Start watching a file descriptor for write availability.
+
+    * - :meth:`loop.remove_writer`
+      - Stop watching a file descriptor for write availability.
+
+
+.. rubric:: Unix Signals
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`loop.add_signal_handler`
+      - Add a handler for a :mod:`signal`.
+
+    * - :meth:`loop.remove_signal_handler`
+      - Remove a handler for a :mod:`signal`.
+
+
+.. rubric:: Subprocesses
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`loop.subprocess_exec`
+      - Spawn a subprocess.
+
+    * - :meth:`loop.subprocess_shell`
+      - Spawn a subprocess from a shell command.
+
+
+.. rubric:: Error Handling
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`loop.call_exception_handler`
+      - Call the exception handler.
+
+    * - :meth:`loop.set_exception_handler`
+      - Set a new exception handler.
+
+    * - :meth:`loop.get_exception_handler`
+      - Get the current exception handler.
+
+    * - :meth:`loop.default_exception_handler`
+      - The default exception handler implementation.
+
+
+.. rubric:: Examples
+
+* :ref:`Using asyncio.get_event_loop() and loop.run_forever()
+  <asyncio_example_lowlevel_helloworld>`.
+
+* :ref:`Using loop.call_later() <asyncio_example_call_later>`.
+
+* Using ``loop.create_connection()`` to implement
+  :ref:`an echo-client <asyncio_example_tcp_echo_client_protocol>`.
+
+* Using ``loop.create_connection()`` to
+  :ref:`connect a socket <asyncio_example_create_connection>`.
+
+* :ref:`Using add_reader() to watch an FD for read events
+  <asyncio_example_watch_fd>`.
+
+* :ref:`Using loop.add_signal_handler() <asyncio_example_unix_signals>`.
+
+* :ref:`Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`.
+
+
+Transports
+==========
+
+All transports implement the following methods:
+
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`transport.close() <BaseTransport.close>`
+      - Close the transport.
+
+    * - :meth:`transport.is_closing() <BaseTransport.is_closing>`
+      - Return ``True`` if the transport is closing or is closed.
+
+    * - :meth:`transport.get_extra_info() <BaseTransport.get_extra_info>`
+      - Request for information about the transport.
+
+    * - :meth:`transport.set_protocol() <BaseTransport.set_protocol>`
+      - Set a new protocol.
+
+    * - :meth:`transport.get_protocol() <BaseTransport.get_protocol>`
+      - Return the current protocol.
+
+
+Transports that can receive data (TCP and Unix connections,
+pipes, etc).  Returned from methods like
+:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
+:meth:`loop.connect_read_pipe`, etc:
+
+.. rubric:: Read Transports
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`transport.is_reading() <ReadTransport.is_reading>`
+      - Return ``True`` if the transport is receiving.
+
+    * - :meth:`transport.pause_reading() <ReadTransport.pause_reading>`
+      - Pause receiving.
+
+    * - :meth:`transport.resume_reading() <ReadTransport.resume_reading>`
+      - Resume receiving.
+
+
+Transports that can Send data (TCP and Unix connections,
+pipes, etc).  Returned from methods like
+:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
+:meth:`loop.connect_write_pipe`, etc:
+
+.. rubric:: Write Transports
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`transport.write() <WriteTransport.write>`
+      - Write data to the transport.
+
+    * - :meth:`transport.writelines() <WriteTransport.writelines>`
+      - Write buffers to the transport.
+
+    * - :meth:`transport.can_write_eof() <WriteTransport.can_write_eof>`
+      - Return :const:`True` if the transport supports sending EOF.
+
+    * - :meth:`transport.write_eof() <WriteTransport.write_eof>`
+      - Close and send EOF after flushing buffered data.
+
+    * - :meth:`transport.abort() <WriteTransport.abort>`
+      - Close the transport immediately.
+
+    * - :meth:`transport.get_write_buffer_size()
+        <WriteTransport.get_write_buffer_size>`
+      - Return high and low water marks for write flow control.
+
+    * - :meth:`transport.set_write_buffer_limits()
+        <WriteTransport.set_write_buffer_limits>`
+      - Set new high and low water marks for write flow control.
+
+
+Transports returned by :meth:`loop.create_datagram_endpoint`:
+
+.. rubric:: Datagram Transports
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`transport.sendto() <DatagramTransport.sendto>`
+      - Send data to the remote peer.
+
+    * - :meth:`transport.abort() <DatagramTransport.abort>`
+      - Close the transport immediately.
+
+
+Low-level transport abstraction over subprocesses.
+Returned by :meth:`loop.subprocess_exec` and
+:meth:`loop.subprocess_shell`:
+
+.. rubric:: Subprocess Transports
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`transport.get_pid() <SubprocessTransport.get_pid>`
+      - Return the subprocess process id.
+
+    * - :meth:`transport.get_pipe_transport()
+        <SubprocessTransport.get_pipe_transport>`
+      - Return the transport for the requested communication pipe
+        (*stdin*, *stdout*, or *stderr*).
+
+    * - :meth:`transport.get_returncode() <SubprocessTransport.get_returncode>`
+      - Return the subprocess return code.
+
+    * - :meth:`transport.kill() <SubprocessTransport.kill>`
+      - Kill the subprocess.
+
+    * - :meth:`transport.send_signal() <SubprocessTransport.send_signal>`
+      - Send a signal to the subprocess.
+
+    * - :meth:`transport.terminate() <SubprocessTransport.terminate>`
+      - Stop the subprocess.
+
+    * - :meth:`transport.close() <SubprocessTransport.close>`
+      - Kill the subprocess and close all pipes.
+
+
+Protocols
+=========
+
+Protocol classes can implement the following **callback methods**:
+
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``callback`` :meth:`connection_made() <BaseProtocol.connection_made>`
+      - Called when a connection is made.
+
+    * - ``callback`` :meth:`connection_lost() <BaseProtocol.connection_lost>`
+      - Called when the connection is lost or closed.
+
+    * - ``callback`` :meth:`pause_writing() <BaseProtocol.pause_writing>`
+      - Called when the transport's buffer goes over the high water mark.
+
+    * - ``callback`` :meth:`resume_writing() <BaseProtocol.resume_writing>`
+      - Called when the transport's buffer drains below the low water mark.
+
+
+.. rubric:: Streaming Protocols (TCP, Unix Sockets, Pipes)
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``callback`` :meth:`data_received() <Protocol.data_received>`
+      - Called when some data is received.
+
+    * - ``callback`` :meth:`eof_received() <Protocol.eof_received>`
+      - Called when an EOF is received.
+
+
+.. rubric:: Buffered Streaming Protocols
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``callback`` :meth:`get_buffer() <BufferedProtocol.get_buffer>`
+      - Called to allocate a new receive buffer.
+
+    * - ``callback`` :meth:`buffer_updated() <BufferedProtocol.buffer_updated>`
+      - Called when the buffer was updated with the received data.
+
+    * - ``callback`` :meth:`eof_received() <BufferedProtocol.eof_received>`
+      - Called when an EOF is received.
+
+
+.. rubric:: Datagram Protocols
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``callback`` :meth:`datagram_received()
+        <DatagramProtocol.datagram_received>`
+      - Called when a datagram is received.
+
+    * - ``callback`` :meth:`error_received() <DatagramProtocol.error_received>`
+      - Called when a previous send or receive operation raises an
+        :class:`OSError`.
+
+
+.. rubric:: Subprocess Protocols
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - ``callback`` :meth:`pipe_data_received()
+        <SubprocessProtocol.pipe_data_received>`
+      - Called when the child process writes data into its
+        *stdout* or *stderr* pipe.
+
+    * - ``callback`` :meth:`pipe_connection_lost()
+        <SubprocessProtocol.pipe_connection_lost>`
+      - Called when one of the pipes communicating with
+        the child process is closed.
+
+    * - ``callback`` :meth:`process_exited()
+        <SubprocessProtocol.process_exited>`
+      - Called when the child process has exited.
+
+
+Event Loop Policies
+===================
+
+Policies is a low-level mechanism to alter the behavior of
+functions like :func:`asyncio.get_event_loop`.  See also
+the main :ref:`policies section <asyncio-policies>` for more
+details.
+
+
+.. rubric:: Accessing Policies
+.. list-table::
+    :widths: 50 50
+    :class: full-width-table
+
+    * - :meth:`asyncio.get_event_loop_policy`
+      - Return the current process-wide policy.
+
+    * - :meth:`asyncio.set_event_loop_policy`
+      - Set a new process-wide policy.
+
+    * - :class:`AbstractEventLoopPolicy`
+      - Base class for policy objects.
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index e4aed64..cb16acd 100644
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -707,7 +707,7 @@ factories passed to the :meth:`loop.subprocess_exec` and
 Examples
 ========
 
-.. _asyncio-tcp-echo-server-protocol:
+.. _asyncio_example_tcp_echo_server_protocol:
 
 TCP Echo Server
 ---------------
@@ -756,7 +756,7 @@ received data, and close the connection::
    The :ref:`TCP echo server using streams <asyncio-tcp-echo-server-streams>`
    example uses the high-level :func:`asyncio.start_server` function.
 
-.. _asyncio-tcp-echo-client-protocol:
+.. _asyncio_example_tcp_echo_client_protocol:
 
 TCP Echo Client
 ---------------
@@ -914,7 +914,7 @@ method, sends data and closes the transport when it receives the answer::
     asyncio.run(main())
 
 
-.. _asyncio-register-socket:
+.. _asyncio_example_create_connection:
 
 Connecting Existing Sockets
 ---------------------------
@@ -973,14 +973,14 @@ Wait until a socket receives data using the
 .. seealso::
 
    The :ref:`watch a file descriptor for read events
-   <asyncio-watch-read-event>` example uses the low-level
+   <asyncio_example_watch_fd>` example uses the low-level
    :meth:`loop.add_reader` method to register an FD.
 
    The :ref:`register an open socket to wait for data using streams
-   <asyncio-register-socket-streams>` example uses high-level streams
+   <asyncio_example_create_connection-streams>` example uses high-level streams
    created by the :func:`open_connection` function in a coroutine.
 
-.. _asyncio-subprocess-proto-example:
+.. _asyncio_example_subprocess_proto:
 
 loop.subprocess_exec() and SubprocessProtocol
 ---------------------------------------------
@@ -1037,3 +1037,6 @@ The subprocess is created by th :meth:`loop.subprocess_exec` method::
 
     date = asyncio.run(get_date())
     print(f"Current date: {date}")
+
+See also the :ref:`same example <asyncio_example_create_subprocess_exec>`
+written using high-level APIs.
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 29163a2..0489201 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -348,7 +348,7 @@ TCP echo client using the :func:`asyncio.open_connection` function::
 
 .. seealso::
 
-   The :ref:`TCP echo client protocol <asyncio-tcp-echo-client-protocol>`
+   The :ref:`TCP echo client protocol <asyncio_example_tcp_echo_client_protocol>`
    example uses the low-level :meth:`loop.create_connection` method.
 
 
@@ -390,7 +390,7 @@ TCP echo server using the :func:`asyncio.start_server` function::
 
 .. seealso::
 
-   The :ref:`TCP echo server protocol <asyncio-tcp-echo-server-protocol>`
+   The :ref:`TCP echo server protocol <asyncio_example_tcp_echo_server_protocol>`
    example uses the :meth:`loop.create_server` method.
 
 
@@ -444,7 +444,7 @@ or with HTTPS::
     python example.py https://example.com/path/page.html
 
 
-.. _asyncio-register-socket-streams:
+.. _asyncio_example_create_connection-streams:
 
 Register an open socket to wait for data using streams
 ------------------------------------------------------
@@ -484,9 +484,9 @@ Coroutine waiting until a socket receives data using the
 .. seealso::
 
    The :ref:`register an open socket to wait for data using a protocol
-   <asyncio-register-socket>` example uses a low-level protocol and
+   <asyncio_example_create_connection>` example uses a low-level protocol and
    the :meth:`loop.create_connection` method.
 
    The :ref:`watch a file descriptor for read events
-   <asyncio-watch-read-event>` example uses the low-level
+   <asyncio_example_watch_fd>` example uses the low-level
    :meth:`loop.add_reader` method to watch a file descriptor.
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index ef8a1cb..57a7a37 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -318,6 +318,8 @@ An example using the :class:`~asyncio.subprocess.Process` class to
 control a subprocess and the :class:`StreamReader` class to read from
 the *stdout*.
 
+.. _asyncio_example_create_subprocess_exec:
+
 The subprocess is created by the :func:`create_subprocess_exec`
 function::
 
@@ -349,5 +351,5 @@ function::
     print(f"Current date: {date}")
 
 
-See also the :ref:`same example <asyncio-subprocess-proto-example>`
+See also the :ref:`same example <asyncio_example_subprocess_proto>`
 written using low-level APIs.
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index d3cfd5f..3faaf0c 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -130,7 +130,7 @@ Running an asyncio Program
     programs, and should ideally only be called once.
 
     .. versionadded:: 3.7
-       **Important:** this has been been added to asyncio in Python 3.7
+       **Important:** this has been added to asyncio in Python 3.7
        on a :term:`provisional basis <provisional api>`.
 
 
@@ -188,7 +188,7 @@ Sleeping
 Running Tasks Concurrently
 ==========================
 
-.. coroutinefunction:: gather(\*fs, loop=None, return_exceptions=False)
+.. function:: gather(\*fs, loop=None, return_exceptions=False)
 
    Return a Future aggregating results from the given coroutine objects,
    Tasks, or Futures.
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
index 9f45f74..7895826 100644
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -43,12 +43,13 @@ as well as **low-level** APIs for *library and framework developers* to:
   with async/await syntax.
 
 
-Reference
----------
+.. We use the "rubric" directive here to avoid creating
+   the "Reference" subsection in the TOC.
 
-.. rubric:: High-level APIs
+.. rubric:: Reference
 
 .. toctree::
+   :caption: High-level APIs
    :maxdepth: 1
 
    asyncio-task.rst
@@ -58,9 +59,8 @@ Reference
    asyncio-queue.rst
    asyncio-exceptions.rst
 
-.. rubric:: Low-level APIs
-
 .. toctree::
+   :caption: Low-level APIs
    :maxdepth: 1
 
    asyncio-eventloop.rst
@@ -69,10 +69,10 @@ Reference
    asyncio-policy.rst
    asyncio-platforms.rst
 
-.. rubric:: Guides and Tutorials
-
 .. toctree::
+   :caption: Guides and Tutorials
    :maxdepth: 1
 
    asyncio-api-index.rst
+   asyncio-llapi-index.rst
    asyncio-dev.rst
diff --git a/Doc/tools/templates/layout.html b/Doc/tools/templates/layout.html
index 3781172..c399224 100644
--- a/Doc/tools/templates/layout.html
+++ b/Doc/tools/templates/layout.html
@@ -21,5 +21,14 @@
       {% if pagename == 'whatsnew/changelog' and not embedded %}
       <script type="text/javascript" src="{{ pathto('_static/changelog_search.js', 1) }}"></script>{% endif %}
     {% endif %}
+
+    {# custom CSS; used in asyncio docs! #}
+    <style>
+      @media only screen {{ "{" }}
+        table.full-width-table {{ "{" }}
+            width: 100%;
+        {{ "}" }}
+      {{ "}" }}
+    </style>
 {{ super() }}
 {% endblock %}