Review reference docs.

Remove sphinx-autodoc-typehints and use native autodoc features
instead, mainly because I can't find a workaround for:
https://github.com/agronholm/sphinx-autodoc-typehints/issues/132

Re-introduce the "common" docs, else linking to send() and recv()
is a mess.

Author: aaugustin

docs/conf.py

@@ -31,21 +31,52 @@
 
 # -- General configuration ---------------------------------------------------
 
+nitpicky = True
+
+nitpick_ignore = [
+    # topics/design.rst discusses undocumented APIs
+    ("py:meth", "client.WebSocketClientProtocol.handshake"),
+    ("py:meth", "server.WebSocketServerProtocol.handshake"),
+    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.is_client"),
+    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.messages"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.close_connection"),
+    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.close_connection_task"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.keepalive_ping"),
+    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.keepalive_ping_task"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.transfer_data"),
+    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.transfer_data_task"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.connection_open"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.ensure_open"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.fail_connection"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.connection_lost"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.read_message"),
+    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.write_frame"),
+]
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
-    "sphinx_autodoc_typehints",
+    "sphinx.ext.napoleon",
     "sphinx_copybutton",
     "sphinx_inline_tabs",
     "sphinxcontrib.spelling",
     "sphinxcontrib_trio",
     "sphinxext.opengraph",
 ]
 
+autodoc_typehints = "description"
+
+autodoc_typehints_description_target = "documented"
+
+# Workaround for https://github.com/sphinx-doc/sphinx/issues/9560
+from sphinx.domains.python import PythonDomain
+assert PythonDomain.object_types['data'].roles == ('data', 'obj')
+PythonDomain.object_types['data'].roles = ('data', 'class', 'obj')
+
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 spelling_show_suggestions = True

docs/howto/cheatsheet.rst

@@ -26,27 +26,27 @@ Server
     :meth:`~legacy.protocol.WebSocketCommonProtocol.pong` if you wish but it isn't
     needed in general.
 
-* Create a server with :func:`~legacy.server.serve` which is similar to asyncio's
-  :meth:`~asyncio.AbstractEventLoop.create_server`. You can also use it as an
-  asynchronous context manager.
+* Create a server with :func:`~server.serve` which is similar to asyncio's
+  :meth:`~asyncio.loop.create_server`. You can also use it as an asynchronous
+  context manager.
 
   * The server takes care of establishing connections, then lets the handler
     execute the application logic, and finally closes the connection after the
     handler exits normally or with an exception.
 
   * For advanced customization, you may subclass
-    :class:`~legacy.server.WebSocketServerProtocol` and pass either this subclass or
+    :class:`~server.WebSocketServerProtocol` and pass either this subclass or
     a factory function as the ``create_protocol`` argument.
 
 Client
 ------
 
-* Create a client with :func:`~legacy.client.connect` which is similar to asyncio's
-  :meth:`~asyncio.BaseEventLoop.create_connection`. You can also use it as an
+* Create a client with :func:`~client.connect` which is similar to asyncio's
+  :meth:`~asyncio.loop.create_connection`. You can also use it as an
   asynchronous context manager.
 
   * For advanced customization, you may subclass
-    :class:`~legacy.server.WebSocketClientProtocol` and pass either this subclass or
+    :class:`~client.WebSocketClientProtocol` and pass either this subclass or
     a factory function as the ``create_protocol`` argument.
 
 * Call :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` and
@@ -57,7 +57,7 @@ Client
   :meth:`~legacy.protocol.WebSocketCommonProtocol.pong` if you wish but it isn't
   needed in general.
 
-* If you aren't using :func:`~legacy.client.connect` as a context manager, call
+* If you aren't using :func:`~client.connect` as a context manager, call
   :meth:`~legacy.protocol.WebSocketCommonProtocol.close` to terminate the connection.
 
 .. _debugging:

docs/howto/django.rst

@@ -124,7 +124,7 @@ support asynchronous I/O. It would block the event loop if it didn't run in a
 separate thread. :func:`~asyncio.to_thread` is available since Python 3.9. In
 earlier versions, use :meth:`~asyncio.loop.run_in_executor` instead.
 
-Finally, we start a server with :func:`~websockets.serve`.
+Finally, we start a server with :func:`~websockets.server.serve`.
 
 We're ready to test!
 

docs/howto/extensions.rst

@@ -4,8 +4,10 @@ Writing an extension
 .. currentmodule:: websockets.extensions
 
 During the opening handshake, WebSocket clients and servers negotiate which
-extensions will be used with which parameters. Then each frame is processed by
-extensions before being sent or after being received.
+extensions_ will be used with which parameters. Then each frame is processed
+by extensions before being sent or after being received.
+
+.. _extensions: https://www.rfc-editor.org/rfc/rfc6455.html#section-9
 
 As a consequence, writing an extension requires implementing several classes:
 
@@ -23,11 +25,8 @@ As a consequence, writing an extension requires implementing several classes:
   Extensions are initialized by extension factories, so they don't need to be
   part of the public API of an extension.
 
-websockets provides abstract base classes for extension factories and
-extensions. See the API documentation for details on their methods:
-
-* :class:`ClientExtensionFactory` and :class:`ServerExtensionFactory` for
-  extension factories,
-* :class:`Extension` for extensions.
+websockets provides base classes for extension factories and extensions.
+See :class:`ClientExtensionFactory`, :class:`ServerExtensionFactory`,
+and :class:`Extension` for details.
 
 

docs/howto/faq.rst

@@ -5,7 +5,7 @@ FAQ
 
 .. note::
 
-    Many questions asked in :mod:`websockets`' issue tracker are actually
+    Many questions asked in websockets' issue tracker are actually
     about :mod:`asyncio`. Python's documentation about `developing with
     asyncio`_ is a good complement.
 
@@ -99,13 +99,13 @@ How do I get access HTTP headers, for example cookies?
 ......................................................
 
 To access HTTP headers during the WebSocket handshake, you can override
-:attr:`~legacy.server.WebSocketServerProtocol.process_request`::
+:attr:`~server.WebSocketServerProtocol.process_request`::
 
     async def process_request(self, path, request_headers):
         cookies = request_header["Cookie"]
 
 Once the connection is established, they're available in
-:attr:`~legacy.protocol.WebSocketServerProtocol.request_headers`::
+:attr:`~server.WebSocketServerProtocol.request_headers`::
 
     async def handler(websocket, path):
         cookies = websocket.request_headers["Cookie"]
@@ -123,7 +123,7 @@ How do I set which IP addresses my server listens to?
 
 Look at the ``host`` argument of :meth:`~asyncio.loop.create_server`.
 
-:func:`serve` accepts the same arguments as
+:func:`~server.serve` accepts the same arguments as
 :meth:`~asyncio.loop.create_server`.
 
 How do I close a connection properly?
@@ -143,7 +143,7 @@ Providing a HTTP server is out of scope for websockets. It only aims at
 providing a WebSocket server.
 
 There's limited support for returning HTTP responses with the
-:attr:`~legacy.server.WebSocketServerProtocol.process_request` hook.
+:attr:`~server.WebSocketServerProtocol.process_request` hook.
 
 If you need more, pick a HTTP server and run it separately.
 
@@ -169,7 +169,7 @@ change it to::
 How do I close a connection properly?
 .....................................
 
-The easiest is to use :func:`connect` as a context manager::
+The easiest is to use :func:`~client.connect` as a context manager::
 
     async with connect(...) as websocket:
         ...
@@ -196,7 +196,7 @@ How do I disable TLS/SSL certificate verification?
 
 Look at the ``ssl`` argument of :meth:`~asyncio.loop.create_connection`.
 
-:func:`connect` accepts the same arguments as
+:func:`~client.connect` accepts the same arguments as
 :meth:`~asyncio.loop.create_connection`.
 
 asyncio usage
@@ -449,4 +449,4 @@ I'm having problems with threads
 
 You shouldn't use threads. Use tasks instead.
 
-:func:`~asyncio.AbstractEventLoop.call_soon_threadsafe` may help.
+:meth:`~asyncio.loop.call_soon_threadsafe` may help.

docs/intro/index.rst

@@ -82,7 +82,7 @@ This client needs a context because the server uses a self-signed certificate.
 
 A client connecting to a secure WebSocket server with a valid certificate
 (i.e. signed by a CA that your Python installation trusts) can simply pass
-``ssl=True`` to :func:`connect` instead of building a context.
+``ssl=True`` to :func:`~client.connect` instead of building a context.
 
 Browser-based example
 ---------------------