Restructure API reference.

python-websockets · Feb 19, 2023 · 206d7ef · 206d7ef
1 parent 8f0a33c
commit 206d7ef
Show file tree

Hide file tree

Showing 16 changed files with 278 additions and 238 deletions.
diff --git a/docs/faq/misc.rst b/docs/faq/misc.rst
@@ -10,6 +10,8 @@ Often, this is because you created a script called ``websockets.py`` in your
 current working directory. Then ``import websockets`` imports this module
 instead of the websockets library.
 
+.. _real-import-paths:
+
 Why does my IDE fail to show documentation for websockets APIs?
 ...............................................................
 

diff --git a/docs/project/changelog.rst b/docs/project/changelog.rst
@@ -22,8 +22,9 @@ When a release contains backwards-incompatible API changes, the major version
 is increased, else the minor version is increased. Patch versions are only for
 fixing regressions shortly after a release.
 
-Only documented APIs are public. Undocumented APIs are considered private.
-They may change at any time.
+Only documented API are public. Undocumented, private API may change without
+notice.
+
 
 11.0
 ----

diff --git a/docs/reference/client.rst → docs/reference/asyncio/client.rst b/docs/reference/client.rst → docs/reference/asyncio/client.rst
@@ -1,13 +1,10 @@
-Client
-======
+Client (:mod:`asyncio`)
+=======================
 
 .. automodule:: websockets.client
 
-asyncio
--------
-
 Opening a connection
-....................
+--------------------
 
 .. autofunction:: connect(uri, *, create_protocol=None, logger=None, compression="deflate", origin=None, extensions=None, subprotocols=None, extra_headers=None, user_agent_header="Python/x.y.z websockets/X.Y", open_timeout=10, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, **kwds)
     :async:
@@ -16,7 +13,7 @@ Opening a connection
     :async:
 
 Using a connection
-..................
+------------------
 
 .. autoclass:: WebSocketClientProtocol(*, logger=None, origin=None, extensions=None, subprotocols=None, extra_headers=None, user_agent_header="Python/x.y.z websockets/X.Y", ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16)
 
@@ -65,50 +62,3 @@ Using a connection
     .. autoproperty:: close_code
 
     .. autoproperty:: close_reason
-
-Sans-I/O
---------
-
-.. autoclass:: ClientProtocol(wsuri, origin=None, extensions=None, subprotocols=None, state=State.CONNECTING, max_size=2 ** 20, logger=None)
-
-    .. automethod:: receive_data
-
-    .. automethod:: receive_eof
-
-    .. automethod:: connect
-
-    .. automethod:: send_request
-
-    .. automethod:: send_continuation
-
-    .. automethod:: send_text
-
-    .. automethod:: send_binary
-
-    .. automethod:: send_close
-
-    .. automethod:: send_ping
-
-    .. automethod:: send_pong
-
-    .. automethod:: fail
-
-    .. automethod:: events_received
-
-    .. automethod:: data_to_send
-
-    .. automethod:: close_expected
-
-    .. autoattribute:: id
-
-    .. autoattribute:: logger
-
-    .. autoproperty:: state
-
-    .. autoattribute:: handshake_exc
-
-    .. autoproperty:: close_code
-
-    .. autoproperty:: close_reason
-
-    .. autoproperty:: close_exc
diff --git a/docs/reference/common.rst → docs/reference/asyncio/common.rst b/docs/reference/common.rst → docs/reference/asyncio/common.rst
@@ -1,8 +1,5 @@
-Both sides
-==========
-
-asyncio
--------
+Both sides (:mod:`asyncio`)
+===========================
 
 .. automodule:: websockets.legacy.protocol
 
@@ -53,64 +50,3 @@ asyncio
     .. autoproperty:: close_code
 
     .. autoproperty:: close_reason
-
-Sans-I/O
---------
-
-.. automodule:: websockets.protocol
-
-.. autoclass:: Protocol(side, state=State.OPEN, max_size=2 ** 20, logger=None)
-
-    .. automethod:: receive_data
-
-    .. automethod:: receive_eof
-
-    .. automethod:: send_continuation
-
-    .. automethod:: send_text
-
-    .. automethod:: send_binary
-
-    .. automethod:: send_close
-
-    .. automethod:: send_ping
-
-    .. automethod:: send_pong
-
-    .. automethod:: fail
-
-    .. automethod:: events_received
-
-    .. automethod:: data_to_send
-
-    .. automethod:: close_expected
-
-    .. autoattribute:: id
-
-    .. autoattribute:: logger
-
-    .. autoproperty:: state
-
-    .. autoproperty:: close_code
-
-    .. autoproperty:: close_reason
-
-    .. autoproperty:: close_exc
-
-.. autoclass:: Side
-
-    .. autoattribute:: SERVER
-
-    .. autoattribute:: CLIENT
-
-.. autoclass:: State
-
-    .. autoattribute:: CONNECTING
-
-    .. autoattribute:: OPEN
-
-    .. autoattribute:: CLOSING
-
-    .. autoattribute:: CLOSED
-
-.. autodata:: SEND_EOF
diff --git a/docs/reference/server.rst → docs/reference/asyncio/server.rst b/docs/reference/server.rst → docs/reference/asyncio/server.rst
@@ -1,13 +1,10 @@
-Server
-======
+Server (:mod:`asyncio`)
+=======================
 
 .. automodule:: websockets.server
 
-asyncio
--------
-
 Starting a server
-.................
+-----------------
 
 .. autofunction:: serve(ws_handler, host=None, port=None, *, create_protocol=None, logger=None, compression="deflate", origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, **kwds)
     :async:
@@ -16,7 +13,7 @@ Starting a server
     :async:
 
 Stopping a server
-.................
+-----------------
 
 .. autoclass:: WebSocketServer
 
@@ -35,7 +32,7 @@ Stopping a server
     .. autoattribute:: sockets
 
 Using a connection
-..................
+------------------
 
 .. autoclass:: WebSocketServerProtocol(ws_handler, ws_server, *, logger=None, origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16)
 
@@ -93,7 +90,7 @@ Using a connection
 
 
 Basic authentication
-....................
+--------------------
 
 .. automodule:: websockets.auth
 
@@ -110,55 +107,7 @@ websockets supports HTTP Basic Authentication according to
 
     .. automethod:: check_credentials
 
-.. currentmodule:: websockets.server
-
-Sans-I/O
---------
-
-.. autoclass:: ServerProtocol(origins=None, extensions=None, subprotocols=None, state=State.CONNECTING, max_size=2 ** 20, logger=None)
-
-    .. automethod:: receive_data
-
-    .. automethod:: receive_eof
-
-    .. automethod:: accept
-
-    .. automethod:: select_subprotocol
-
-    .. automethod:: reject
-
-    .. automethod:: send_response
-
-    .. automethod:: send_continuation
-
-    .. automethod:: send_text
-
-    .. automethod:: send_binary
-
-    .. automethod:: send_close
-
-    .. automethod:: send_ping
-
-    .. automethod:: send_pong
-
-    .. automethod:: fail
-
-    .. automethod:: events_received
-
-    .. automethod:: data_to_send
-
-    .. automethod:: close_expected
-
-    .. autoattribute:: id
-
-    .. autoattribute:: logger
-
-    .. autoproperty:: state
-
-    .. autoattribute:: handshake_exc
-
-    .. autoproperty:: close_code
-
-    .. autoproperty:: close_reason
+Broadcast
+---------
 
-    .. autoproperty:: close_exc
+.. autofunction:: websockets.broadcast
diff --git a/docs/reference/utilities.rst → docs/reference/datastructures.rst b/docs/reference/utilities.rst → docs/reference/datastructures.rst
@@ -1,10 +1,5 @@
-Utilities
-=========
-
-Broadcast
----------
-
-.. autofunction:: websockets.broadcast
+Data structures
+===============
 
 WebSocket events
 ----------------