Skip to content

Commit 58614d0

Browse files
aaugustinaaugustin
committed
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.
1 parent 4596e9d commit 58614d0

34 files changed

+740
-558
lines changed

‎docs/conf.py

+10-1
Original file line numberDiff line numberDiff line change
@@ -38,14 +38,23 @@
3838
"sphinx.ext.autodoc",
3939
"sphinx.ext.intersphinx",
4040
"sphinx.ext.linkcode",
41-
"sphinx_autodoc_typehints",
41+
"sphinx.ext.napoleon",
4242
"sphinx_copybutton",
4343
"sphinx_inline_tabs",
4444
"sphinxcontrib.spelling",
4545
"sphinxcontrib_trio",
4646
"sphinxext.opengraph",
4747
]
4848

49+
autodoc_typehints = "description"
50+
51+
autodoc_typehints_description_target = "documented"
52+
53+
# Workaround for https://github.com/sphinx-doc/sphinx/issues/9560
54+
from sphinx.domains.python import PythonDomain
55+
assert PythonDomain.object_types['data'].roles == ('data', 'obj')
56+
PythonDomain.object_types['data'].roles = ('data', 'class', 'obj')
57+
4958
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
5059

5160
spelling_show_suggestions = True

‎docs/howto/extensions.rst

+7-8
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,10 @@ Writing an extension
44
.. currentmodule:: websockets.extensions
55

66
During the opening handshake, WebSocket clients and servers negotiate which
7-
extensions will be used with which parameters. Then each frame is processed by
8-
extensions before being sent or after being received.
7+
extensions_ will be used with which parameters. Then each frame is processed
8+
by extensions before being sent or after being received.
9+
10+
.. _extensions: https://www.rfc-editor.org/rfc/rfc6455.html#section-9
911

1012
As a consequence, writing an extension requires implementing several classes:
1113

@@ -23,11 +25,8 @@ As a consequence, writing an extension requires implementing several classes:
2325
Extensions are initialized by extension factories, so they don't need to be
2426
part of the public API of an extension.
2527

26-
websockets provides abstract base classes for extension factories and
27-
extensions. See the API documentation for details on their methods:
28-
29-
* :class:`ClientExtensionFactory` and :class:`ServerExtensionFactory` for
30-
extension factories,
31-
* :class:`Extension` for extensions.
28+
websockets provides base classes for extension factories and extensions.
29+
See :class:`ClientExtensionFactory`, :class:`ServerExtensionFactory`,
30+
and :class:`Extension` for details.
3231

3332

‎docs/reference/client.rst

+3-57
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,18 @@
11
Client
22
======
3-
43
.. automodule:: websockets.client
54

65
Opening a connection
76
--------------------
87

9-
.. 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, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, logger=None, **kwds)
8+
.. autofunction:: connect(uri, *, create_protocol=None, logger=None, compression="deflate", origin=None, extensions=None, subprotocols=None, extra_headers=None, 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)
109
:async:
1110

12-
.. 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, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, logger=None, **kwds)
11+
.. autofunction:: unix_connect(path, uri="ws://localhost/", *, create_protocol=None, logger=None, compression="deflate", origin=None, extensions=None, subprotocols=None, extra_headers=None, 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)
1312
:async:
1413

1514
Using a connection
1615
------------------
1716

18-
.. 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, origin=None, extensions=None, subprotocols=None, extra_headers=None, logger=None)
19-
20-
.. attribute:: id
21-
22-
UUID for the connection.
23-
24-
Useful for identifying connections in logs.
25-
26-
.. autoattribute:: local_address
27-
28-
.. autoattribute:: remote_address
29-
30-
.. autoattribute:: open
31-
32-
.. autoattribute:: closed
33-
34-
.. attribute:: path
35-
36-
Path of the HTTP request.
37-
38-
Available once the connection is open.
39-
40-
.. attribute:: request_headers
41-
42-
HTTP request headers as a :class:`~websockets.http.Headers` instance.
43-
44-
Available once the connection is open.
45-
46-
.. attribute:: response_headers
47-
48-
HTTP response headers as a :class:`~websockets.http.Headers` instance.
49-
50-
Available once the connection is open.
51-
52-
.. attribute:: subprotocol
53-
54-
Subprotocol, if one was negotiated.
55-
56-
Available once the connection is open.
57-
58-
.. autoattribute:: close_code
59-
60-
.. autoattribute:: close_reason
61-
62-
.. automethod:: recv
63-
64-
.. automethod:: send
65-
66-
.. automethod:: ping
67-
68-
.. automethod:: pong
69-
70-
.. automethod:: close
17+
.. autoclass:: WebSocketClientProtocol(*, logger=None, origin=None, extensions=None, subprotocols=None, extra_headers=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)
7118

72-
.. automethod:: wait_closed

‎docs/reference/common.rst

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
Both sides
2+
==========
3+
4+
.. automodule:: websockets.legacy.protocol
5+
6+
.. autoclass:: WebSocketCommonProtocol(*, 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, logger=None)
7+
8+
.. automethod:: recv
9+
10+
.. automethod:: send
11+
12+
.. automethod:: ping
13+
14+
.. automethod:: pong
15+
16+
.. automethod:: close
17+
18+
.. automethod:: wait_closed
19+
20+
WebSocket connection objects also provide these attributes:
21+
22+
.. attribute:: id
23+
24+
UUID for the connection.
25+
26+
Useful for identifying connections in logs.
27+
28+
:type: :class:`~uuid.UUID`
29+
30+
.. autoattribute:: local_address
31+
32+
:type: :obj:`~typing.Any`
33+
34+
.. autoattribute:: remote_address
35+
36+
:type: :obj:`~typing.Any`
37+
38+
.. autoattribute:: open
39+
40+
.. autoattribute:: closed
41+
42+
The following attributes are available after the opening handshake,
43+
once the connection is open:
44+
45+
.. attribute:: path
46+
47+
Path of the opening handshake request.
48+
49+
:type: :class:`str`
50+
51+
.. attribute:: request_headers
52+
53+
Opening handshake request headers.
54+
55+
:type: :class:`~websockets.datastructures.Headers`
56+
57+
.. attribute:: response_headers
58+
59+
Opening handshake response headers.
60+
61+
:type: :class:`~websockets.datastructures.Headers`
62+
63+
.. attribute:: subprotocol
64+
65+
Subprotocol, if one was negotiated.
66+
67+
:type: :obj:`~typing.Optional`\[:data:`~websockets.typing.Subprotocol`]
68+
69+
The following attributes are available after the closing handshake,
70+
once the connection is closed:
71+
72+
.. autoattribute:: close_code
73+
74+
:type: :obj:`~typing.Optional`\[:class:`int`]
75+
76+
.. autoattribute:: close_reason
77+
78+
:type: :obj:`~typing.Optional`\[:class:`str`]

‎docs/reference/exceptions.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Exceptions
2+
==========
3+
4+
.. automodule:: websockets.exceptions
5+
:members:
6+

‎docs/reference/extensions.rst

+29-6
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Extensions
66
The WebSocket protocol supports extensions_.
77

88
At the time of writing, there's only one `registered extension`_ with a public
9-
specification, WebSocket Per-Message Deflate, specified in :rfc:`7692`.
9+
specification, WebSocket Per-Message Deflate.
1010

1111
.. _extensions: https://www.rfc-editor.org/rfc/rfc6455.html#section-9
1212
.. _registered extension: https://www.iana.org/assignments/websocket/websocket.xhtml#extension-name
@@ -16,21 +16,44 @@ Per-Message Deflate
1616

1717
.. automodule:: websockets.extensions.permessage_deflate
1818

19+
:mod:`websockets.extensions.permessage_deflate` implements WebSocket
20+
Per-Message Deflate.
21+
22+
This extension is specified in :rfc:`7692`.
23+
24+
Refer to the :doc:`topic guide on compression <../topics/compression>` to
25+
learn more about tuning compression settings.
26+
1927
.. autoclass:: ClientPerMessageDeflateFactory
2028

2129
.. autoclass:: ServerPerMessageDeflateFactory
2230

23-
Abstract classes
24-
----------------
31+
Base classes
32+
------------
2533

2634
.. automodule:: websockets.extensions
2735

36+
:mod:`websockets.extensions` defines base clases for implementing extensions.
37+
38+
Refer to the :doc:`how-to guide on extensions <../howto/extensions>` to
39+
learn more about writing an extension.
40+
2841
.. autoclass:: Extension
29-
:members:
42+
43+
.. autoattribute:: name
44+
45+
.. automethod:: decode
46+
47+
.. automethod:: encode
3048

3149
.. autoclass:: ClientExtensionFactory
32-
:members:
50+
51+
.. autoattribute:: name
52+
53+
.. automethod:: get_request_params
54+
55+
.. automethod:: process_response_params
3356

3457
.. autoclass:: ServerExtensionFactory
35-
:members:
3658

59+
.. automethod:: process_request_params

‎docs/reference/index.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,11 @@ both in the client API and server API.
4242

4343
client
4444
server
45-
extensions
45+
common
4646
utilities
47+
exceptions
48+
types
49+
extensions
4750
limitations
4851

4952
All public APIs can be imported from the :mod:`websockets` package, unless

‎docs/reference/limitations.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
Limitations
22
===========
33

4+
.. currentmodule:: websockets
5+
46
Client
57
------
68

79
The client doesn't attempt to guarantee that there is no more than one
810
connection to a given IP address in a CONNECTING state. This behavior is
9-
`mandated by RFC 6455`_. However, :func:`~websockets.connect()` isn't the
11+
`mandated by RFC 6455`_. However, :func:`~client.connect()` isn't the
1012
right layer for enforcing this constraint. It's the caller's responsibility.
1113

1214
.. _mandated by RFC 6455: https://www.rfc-editor.org/rfc/rfc6455.html#section-4.1

‎docs/reference/server.rst

-54
Original file line numberDiff line numberDiff line change
@@ -27,64 +27,10 @@ Server
2727

2828
.. 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, origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, logger=None)
2929

30-
.. attribute:: id
31-
32-
UUID for the connection.
33-
34-
Useful for identifying connections in logs.
35-
36-
.. autoattribute:: local_address
37-
38-
.. autoattribute:: remote_address
39-
40-
.. autoattribute:: open
41-
42-
.. autoattribute:: closed
43-
44-
.. attribute:: path
45-
46-
Path of the HTTP request.
47-
48-
Available once the connection is open.
49-
50-
.. attribute:: request_headers
51-
52-
HTTP request headers as a :class:`~websockets.http.Headers` instance.
53-
54-
Available once the connection is open.
55-
56-
.. attribute:: response_headers
57-
58-
HTTP response headers as a :class:`~websockets.http.Headers` instance.
59-
60-
Available once the connection is open.
61-
62-
.. attribute:: subprotocol
63-
64-
Subprotocol, if one was negotiated.
65-
66-
Available once the connection is open.
67-
68-
.. autoattribute:: close_code
69-
70-
.. autoattribute:: close_reason
71-
7230
.. automethod:: process_request
7331

7432
.. automethod:: select_subprotocol
7533

76-
.. automethod:: recv
77-
78-
.. automethod:: send
79-
80-
.. automethod:: ping
81-
82-
.. automethod:: pong
83-
84-
.. automethod:: close
85-
86-
.. automethod:: wait_closed
87-
8834
Basic authentication
8935
--------------------
9036

‎docs/reference/types.rst

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Types
2+
=====
3+
4+
.. automodule:: websockets.typing
5+
6+
.. autodata:: Data
7+
8+
.. autodata:: LoggerLike
9+
10+
.. autodata:: Origin
11+
12+
.. autodata:: Subprotocol
13+
14+
.. autodata:: ExtensionName
15+
16+
.. autodata:: ExtensionParameter
17+

0 commit comments

Comments
 (0)