Revamp API documentation.

docs/api/client.rst

@@ -0,0 +1,74 @@
+Client
+======
+
+.. automodule:: websockets.legacy.client
+
+    Opening a connection
+    --------------------
+
+    .. autofunction:: connect(uri, *, create_protocol=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, loop=None, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, **kwds)
+        :async:
+
+    .. autofunction:: unix_connect(path, uri="ws://localhost/", *, create_protocol=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, loop=None, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, **kwds)
+        :async:
+
+    Using a connection
+    ------------------
+
+    .. autoclass:: WebSocketClientProtocol(*, 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, loop=None, origin=None, extensions=None, subprotocols=None, extra_headers=None)
+
+        .. autoattribute:: local_address
+
+        .. autoattribute:: remote_address
+
+        .. autoattribute:: open
+
+        .. autoattribute:: closed
+
+        .. attribute:: path
+
+            Path of the HTTP request.
+
+            Available once the connection is open.
+
+        .. attribute:: request_headers
+
+            HTTP request headers as a :class:`~websockets.http.Headers` instance.
+
+            Available once the connection is open.
+
+        .. attribute:: response_headers
+
+            HTTP response headers as a :class:`~websockets.http.Headers` instance.
+
+            Available once the connection is open.
+
+        .. attribute:: subprotocol
+
+            Subprotocol, if one was negotiated.
+
+            Available once the connection is open.
+
+        .. attribute:: close_code
+
+            WebSocket close code.
+
+            Available once the connection is closed.
+
+        .. attribute:: close_reason
+
+            WebSocket close reason.
+
+            Available once the connection is closed.
+
+        .. automethod:: recv
+
+        .. automethod:: send
+
+        .. automethod:: ping
+
+        .. automethod:: pong
+
+        .. automethod:: close
+
+        .. automethod:: wait_closed

docs/api/extensions.rst

@@ -0,0 +1,26 @@
+Extensions
+==========
+
+Per-Message Deflate
+-------------------
+
+.. automodule:: websockets.extensions.permessage_deflate
+
+    .. autoclass:: ClientPerMessageDeflateFactory
+
+    .. autoclass:: ServerPerMessageDeflateFactory
+
+Abstract classes
+----------------
+
+.. automodule:: websockets.extensions.base
+
+    .. autoclass:: Extension
+        :members:
+
+    .. autoclass:: ClientExtensionFactory
+        :members:
+
+    .. autoclass:: ServerExtensionFactory
+        :members:
+

docs/api/index.rst

@@ -0,0 +1,50 @@
+API
+===
+
+``websockets`` provides complete client and server implementations, as shown
+in the :doc:`getting started guide <../intro>`.
+
+The process for opening and closing a WebSocket connection depends on which
+side you're implementing.
+
+* On the client side, connecting to a server with :class:`~websockets.connect`
+  yields a connection object that provides methods for interacting with the
+  connection. Your code can open a connection, then send or receive messages.
+
+  If you use :class:`~websockets.connect` as an asynchronous context manager,
+  then websockets closes the connection on exit. If not, then your code is
+  responsible for closing the connection.
+
+* On the server side, :class:`~websockets.serve` starts listening for client
+  connections and yields an server object that supports closing the server.
+
+  Then, when clients connects, the server initializes a connection object and
+  passes it to a handler coroutine, which is where your code can send or
+  receive messages. This pattern is called `inversion of control`_. It's
+  common in frameworks implementing servers.
+
+  When the handler coroutine terminates, websockets closes the connection. You
+  may also close it in the handler coroutine if you'd like.
+
+.. _inversion of control: https://en.wikipedia.org/wiki/Inversion_of_control
+
+Once the connection is open, the WebSocket protocol is symmetrical, except for
+low-level details that websockets manages under the hood. The same methods are
+available on client connections created with :class:`~websockets.connect` and
+on server connections passed to the connection handler in the arguments.
+
+At this point, websockets provides the same API — and uses the same code — for
+client and server connections. For convenience, common methods are documented
+both in the client API and server API.
+
+.. toctree::
+   :maxdepth: 2
+
+   client
+   server
+   extensions
+   utilities
+
+All public APIs can be imported from the :mod:`websockets` package, unless
+noted otherwise. Anything that isn't listed in this API documentation is a
+private API, with no guarantees of behavior or backwards-compatibility.

docs/api/server.rst

@@ -0,0 +1,105 @@
+Server
+======
+
+.. automodule:: websockets.legacy.server
+
+    Starting a server
+    -----------------
+
+    .. autofunction:: serve(ws_handler, host=None, port=None, *, create_protocol=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, loop=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, **kwds)
+        :async:
+
+    .. autofunction:: unix_serve(ws_handler, path, *, create_protocol=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, loop=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, **kwds)
+        :async:
+
+    Stopping a server
+    -----------------
+
+    .. autoclass:: WebSocketServer
+
+        .. autoattribute:: sockets
+
+        .. automethod:: close
+        .. automethod:: wait_closed
+
+    Using a connection
+    ------------------
+
+    .. autoclass:: WebSocketServerProtocol(ws_handler, ws_server, *, 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, loop=None, origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None)
+
+        .. autoattribute:: local_address
+
+        .. autoattribute:: remote_address
+
+        .. autoattribute:: open
+
+        .. autoattribute:: closed
+
+        .. attribute:: path
+
+            Path of the HTTP request.
+
+            Available once the connection is open.
+
+        .. attribute:: request_headers
+
+            HTTP request headers as a :class:`~websockets.http.Headers` instance.
+
+            Available once the connection is open.
+
+        .. attribute:: response_headers
+
+            HTTP response headers as a :class:`~websockets.http.Headers` instance.
+
+            Available once the connection is open.
+
+        .. attribute:: subprotocol
+
+            Subprotocol, if one was negotiated.
+
+            Available once the connection is open.
+
+        .. attribute:: close_code
+
+            WebSocket close code.
+
+            Available once the connection is closed.
+
+        .. attribute:: close_reason
+
+            WebSocket close reason.
+
+            Available once the connection is closed.
+
+        .. automethod:: process_request
+
+        .. automethod:: select_subprotocol
+
+        .. automethod:: recv
+
+        .. automethod:: send
+
+        .. automethod:: ping
+
+        .. automethod:: pong
+
+        .. automethod:: close
+
+        .. automethod:: wait_closed
+
+Basic authentication
+--------------------
+
+.. automodule:: websockets.legacy.auth
+
+    .. autofunction:: basic_auth_protocol_factory
+
+    .. autoclass:: BasicAuthWebSocketServerProtocol
+
+        .. automethod:: process_request
+
+        .. attribute:: username
+
+            Username of the authenticated user.
+
+