Add more references to QuicConnection.datagrams_to_send

Instead of tediously copying the same text over and over, add a
`aioquic_transmit` Sphinx extension to mark methods for which
`datagrams_to_send` needs to be called.

docs/_ext/sphinx_aioquic.py

@@ -0,0 +1,31 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.statemachine import StringList
+
+
+class AioquicTransmit(Directive):
+    def run(self):
+        content = StringList(
+            [
+                ".. note::",
+                "    After calling this method you need to call the QUIC connection "
+                ":meth:`~aioquic.quic.connection.QuicConnection.datagrams_to_send` "
+                "method to retrieve data which needs to be sent over the network. "
+                "If you are using the :doc:`asyncio API <asyncio>`, calling the "
+                ":meth:`~aioquic.asyncio.QuicConnectionProtocol.transmit` method "
+                "will do it for you.",
+            ]
+        )
+        node = nodes.paragraph()
+        self.state.nested_parse(content, 0, node)
+        return [node]
+
+
+def setup(app):
+    app.add_directive("aioquic_transmit", AioquicTransmit)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/conf.py

@@ -4,6 +4,9 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+import sys
+
 # -- Project information -----------------------------------------------------
 
 project = "aioquic"
@@ -13,6 +16,8 @@
 
 # -- General configuration ------------------------------------------------
 
+sys.path.append(os.path.abspath("./_ext"))
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -21,6 +26,7 @@
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
     "sphinxcontrib_trio",
+    "sphinx_aioquic",
 ]
 intersphinx_mapping = {
     "cryptography": ("https://cryptography.io/en/latest", None),

src/aioquic/h3/connection.py

@@ -348,6 +348,8 @@ def create_webtransport_stream(
         """
         Create a WebTransport stream and return the stream ID.
 
+        .. aioquic_transmit::
+
         :param session_id: The WebTransport session identifier.
         :param is_unidirectional: Whether to create a unidirectional stream.
         """
@@ -403,6 +405,8 @@ def send_datagram(self, stream_id: int, data: bytes) -> None:
         If the stream ID is not a client-initiated bidirectional stream, an
         :class:`~aioquic.h3.exceptions.InvalidStreamTypeError` exception is raised.
 
+        .. aioquic_transmit::
+
         :param stream_id: The stream ID.
         :param data: The HTTP/3 datagram payload.
         """
@@ -427,6 +431,8 @@ def send_push_promise(self, stream_id: int, headers: Headers) -> int:
         If there are not available push IDs, an
         :class:`~aioquic.h3.exceptions.NoAvailablePushIDError` exception is raised.
 
+        .. aioquic_transmit::
+
         :param stream_id: The stream ID on which to send the data.
         :param headers: The HTTP request headers for this push.
         """
@@ -464,9 +470,7 @@ def send_data(self, stream_id: int, data: bytes, end_stream: bool) -> None:
         """
         Send data on the given stream.
 
-        To retrieve datagram which need to be sent over the network call the QUIC
-        connection's :meth:`~aioquic.quic.connection.QuicConnection.datagrams_to_send`
-        method.
+        .. aioquic_transmit::
 
         :param stream_id: The stream ID on which to send the data.
         :param data: The data to send.
@@ -497,9 +501,7 @@ def send_headers(
         """
         Send headers on the given stream.
 
-        To retrieve datagram which need to be sent over the network call the QUIC
-        connection's :meth:`~aioquic.quic.connection.QuicConnection.datagrams_to_send`
-        method.
+        .. aioquic_transmit::
 
         :param stream_id: The stream ID on which to send the headers.
         :param headers: The HTTP headers to send.

src/aioquic/quic/connection.py

@@ -457,8 +457,7 @@ def change_connection_id(self) -> None:
         Switch to the next available connection ID and retire
         the previous one.
 
-        After calling this method call :meth:`datagrams_to_send` to retrieve data
-        which needs to be sent.
+        .. aioquic_transmit::
         """
         if self._peer_cid_available:
             # retire previous CID
@@ -476,6 +475,8 @@ def close(
         """
         Close the connection.
 
+        .. aioquic_transmit::
+
         :param error_code: An error code indicating why the connection is
                            being closed.
         :param reason_phrase: A human-readable explanation of why the
@@ -495,8 +496,7 @@ def connect(self, addr: NetworkAddress, now: float) -> None:
 
         This method can only be called for clients and a single time.
 
-        After calling this method call :meth:`datagrams_to_send` to retrieve data
-        which needs to be sent.
+        .. aioquic_transmit::
 
         :param addr: The network address of the remote peer.
         :param now: The current time.
@@ -686,8 +686,7 @@ def handle_timer(self, now: float) -> None:
         """
         Handle the timer.
 
-        After calling this method call :meth:`datagrams_to_send` to retrieve data
-        which needs to be sent.
+        .. aioquic_transmit::
 
         :param now: The current time.
         """
@@ -722,8 +721,7 @@ def receive_datagram(self, data: bytes, addr: NetworkAddress, now: float) -> Non
         """
         Handle an incoming datagram.
 
-        After calling this method call :meth:`datagrams_to_send` to retrieve data
-        which needs to be sent.
+        .. aioquic_transmit::
 
         :param data: The datagram which was received.
         :param addr: The network address from which the datagram was received.
@@ -1102,6 +1100,8 @@ def receive_datagram(self, data: bytes, addr: NetworkAddress, now: float) -> Non
     def request_key_update(self) -> None:
         """
         Request an update of the encryption keys.
+
+        .. aioquic_transmit::
         """
         assert self._handshake_complete, "cannot change key before handshake completes"
         self._cryptos[tls.Epoch.ONE_RTT].update_key()
@@ -1110,6 +1110,8 @@ def reset_stream(self, stream_id: int, error_code: int) -> None:
         """
         Abruptly terminate the sending part of a stream.
 
+        .. aioquic_transmit::
+
         :param stream_id: The stream's ID.
         :param error_code: An error code indicating why the stream is being reset.
         """
@@ -1120,6 +1122,8 @@ def send_ping(self, uid: int) -> None:
         """
         Send a PING frame to the peer.
 
+        .. aioquic_transmit::
+
         :param uid: A unique ID for this PING.
         """
         self._ping_pending.append(uid)
@@ -1128,6 +1132,8 @@ def send_datagram_frame(self, data: bytes) -> None:
         """
         Send a DATAGRAM frame.
 
+        .. aioquic_transmit::
+
         :param data: The data to be sent.
         """
         self._datagrams_pending.append(data)
@@ -1138,6 +1144,8 @@ def send_stream_data(
         """
         Send data on the specific stream.
 
+        .. aioquic_transmit::
+
         :param stream_id: The stream's ID.
         :param data: The data to be sent.
         :param end_stream: If set to `True`, the FIN bit will be set.
@@ -1149,6 +1157,8 @@ def stop_stream(self, stream_id: int, error_code: int) -> None:
         """
         Request termination of the receiving part of a stream.
 
+        .. aioquic_transmit::
+
         :param stream_id: The stream's ID.
         :param error_code: An error code indicating why the stream is being stopped.
         """