Documentation: Fixed API docstrings (#292)

francis-clairicia · May 9, 2024 · ec58a4c · ec58a4c
1 parent dfff239
commit ec58a4c
Show file tree

Hide file tree

Showing 27 changed files with 481 additions and 272 deletions.
diff --git a/docs/source/_static/css/rtfd.css b/docs/source/_static/css/rtfd.css
@@ -0,0 +1,4 @@
+/* Force content to use more spaces than default (800px) */
+.wy-nav-content {
+    max-width: 1345px;
+}
diff --git a/docs/source/api/lowlevel/async/servers.rst b/docs/source/api/lowlevel/async/servers.rst
@@ -9,9 +9,17 @@ Stream Servers
    :members:
    :no-docstring:
 
+.. autoclass:: easynetwork.lowlevel.api_async.servers.stream::Client()
+   :members:
+   :exclude-members: __init__
+
 Datagram Servers
 ================
 
 .. automodule:: easynetwork.lowlevel.api_async.servers.datagram
    :members:
    :no-docstring:
+
+.. autoclass:: easynetwork.lowlevel.api_async.servers.datagram::DatagramClientContext()
+   :members:
+   :exclude-members: __init__
diff --git a/docs/source/api/lowlevel/sync/transports.rst b/docs/source/api/lowlevel/sync/transports.rst
@@ -11,7 +11,7 @@ Abstract Base Classes
    :no-docstring:
 
 ``selectors``-based transports
-------------------------------
+==============================
 
 .. seealso::
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -8,14 +8,14 @@
 
 import os.path
 import sys
-from importlib.metadata import version as get_version
+from importlib.metadata import version as _get_distribution_version
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 project = "EasyNetwork"
 copyright = "2024, Francis Clairicia-Rose-Claire-Josephine"
 author = "FrankySnow9"
-release = get_version("easynetwork")
+release = _get_distribution_version("easynetwork")
 version = ".".join(release.split(".")[:3])
 
 # -- General configuration ---------------------------------------------------
@@ -66,7 +66,8 @@
 # -- sphinx.ext.autodoc configuration ----------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 
-autoclass_content = "both"
+autoclass_content = "class"
+autodoc_class_signature = "separated"
 autodoc_member_order = "bysource"
 autodoc_default_options = {
     "undoc-members": None,
@@ -75,22 +76,25 @@
     "show-inheritance": None,
 }
 autodoc_preserve_defaults = True
-autodoc_typehints = "description"
+autodoc_typehints = "both"
 autodoc_typehints_description_target = "documented_params"
 autodoc_type_aliases = {
-    "_typing_bz2.BZ2Compressor": "bz2.BZ2Compressor",
-    "_typing_bz2.BZ2Decompressor": "bz2.BZ2Decompressor",
-    "_typing_zlib._Compress": "zlib.Compress",
-    "_typing_zlib._Decompress": "zlib.Decompress",
-    "_typing_pickle.Pickler": "pickle.Pickler",
-    "_typing_pickle.Unpickler": "pickle.Unpickler",
-    "_typing_struct.Struct": "struct.Struct",
-    "_typing_ssl.SSLContext": "ssl.SSLContext",
     "_socket._RetAddress": "typing.Any",
     "_socket.socket": "socket.socket",
+    "BZ2Compressor": "bz2.BZ2Compressor",
+    "BZ2Decompressor": "bz2.BZ2Decompressor",
     "contextvars.Context": "contextvars.Context",
+    "MemoryBIO": "ssl.MemoryBIO",
+    "Pickler": "pickle.Pickler",
     "ReadableBuffer": "bytes | bytearray | memoryview",
+    "SSLContext": "ssl.SSLContext",
+    "SSLSession": "ssl.SSLSession",
+    "SSLSocket": "ssl.SSLSocket",
+    "Struct": "struct.Struct",
+    "Unpickler": "pickle.Unpickler",
     "WriteableBuffer": "bytearray | memoryview",
+    "ZLibCompress": "zlib.Compress",
+    "ZLibDecompress": "zlib.Decompress",
 }
 autodoc_inherit_docstrings = False
 autodoc_mock_imports = [
@@ -148,6 +152,7 @@
 ]
 html_css_files = [
     "css/details.css",
+    "css/rtfd.css",
 ]
 
 # -- sphinx-rtd-theme configuration ------------------------------------------
@@ -156,3 +161,13 @@
 html_theme_options = {
     "navigation_depth": -1,  # Unlimited
 }
+
+
+# -----------------------------------------------------------------------------
+
+
+def setup(app) -> None:
+    import warnings
+    from sphinx import RemovedInNextVersionWarning
+
+    warnings.filterwarnings("ignore", category=RemovedInNextVersionWarning, module="sphinx_toolbox.more_autodoc.autoprotocol")
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -21,6 +21,7 @@ Welcome to EasyNetwork's documentation!
    ------------
 
    * :github:repo:`Source code <francis-clairicia/EasyNetwork>`
+   * `Release Notes <https://github.com/francis-clairicia/EasyNetwork/releases>`_
    * :ref:`genindex`
    * :ref:`modindex`
 
@@ -29,5 +30,6 @@ Welcome to EasyNetwork's documentation!
       :github:
       :pypi: easynetwork
 
+      Release Notes <https://github.com/francis-clairicia/EasyNetwork/releases>
       genindex
       modindex
diff --git a/pdm.lock b/pdm.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -112,11 +112,11 @@ coverage = [
     "coverage~=7.0",
 ]
 doc = [
-    "sphinx>=6.2.1,<7",
-    "sphinx-rtd-theme>=1.2.2",
-    "sphinx-tabs>=3.4.1",
-    "sphinx-toolbox>=3.5.0",
-    "enum-tools[sphinx]>=0.10.0",
+    "sphinx>=7.3,<8",
+    "sphinx-rtd-theme>=2.0,<3",
+    "sphinx-tabs>=3.4.1,<4",
+    "sphinx-toolbox>=3.5.0,<4",
+    "enum-tools[sphinx]>=0.12.0,<1",
 ]
 micro-benchmark = [
     "pytest~=7.4",

diff --git a/src/easynetwork/clients/async_tcp.py b/src/easynetwork/clients/async_tcp.py
@@ -53,7 +53,7 @@
 from .abc import AbstractAsyncNetworkClient
 
 if TYPE_CHECKING:
-    import ssl as _typing_ssl
+    from ssl import SSLContext
 
 
 @dataclasses.dataclass(kw_only=True, slots=True)
@@ -96,7 +96,7 @@ def __init__(
         *,
         local_address: tuple[str, int] | None = ...,
         happy_eyeballs_delay: float | None = ...,
-        ssl: _typing_ssl.SSLContext | bool | None = ...,
+        ssl: SSLContext | bool | None = ...,
         server_hostname: str | None = ...,
         ssl_handshake_timeout: float | None = ...,
         ssl_shutdown_timeout: float | None = ...,
@@ -114,7 +114,7 @@ def __init__(
         protocol: StreamProtocol[_T_SentPacket, _T_ReceivedPacket],
         backend: AsyncBackend | BuiltinAsyncBackendToken | None = ...,
         *,
-        ssl: _typing_ssl.SSLContext | bool | None = ...,
+        ssl: SSLContext | bool | None = ...,
         server_hostname: str | None = ...,
         ssl_handshake_timeout: float | None = ...,
         ssl_shutdown_timeout: float | None = ...,
@@ -131,7 +131,7 @@ def __init__(
         protocol: StreamProtocol[_T_SentPacket, _T_ReceivedPacket],
         backend: AsyncBackend | BuiltinAsyncBackendToken | None = None,
         *,
-        ssl: _typing_ssl.SSLContext | bool | None = None,
+        ssl: SSLContext | bool | None = None,
         server_hostname: str | None = None,
         ssl_handshake_timeout: float | None = None,
         ssl_shutdown_timeout: float | None = None,
@@ -302,7 +302,7 @@ async def __create_ssl_over_tcp_connection(
         backend: AsyncBackend,
         host: str,
         port: int,
-        ssl_context: _typing_ssl.SSLContext,
+        ssl_context: SSLContext,
         *,
         server_hostname: str | None,
         ssl_handshake_timeout: float | None,
@@ -334,7 +334,7 @@ async def __create_ssl_over_tcp_connection(
     async def __wrap_ssl_over_stream_socket_client_side(
         backend: AsyncBackend,
         socket: _socket.socket,
-        ssl_context: _typing_ssl.SSLContext,
+        ssl_context: SSLContext,
         *,
         server_hostname: str,
         ssl_handshake_timeout: float | None,

diff --git a/src/easynetwork/clients/tcp.py b/src/easynetwork/clients/tcp.py
@@ -51,7 +51,7 @@
 from .abc import AbstractNetworkClient
 
 if TYPE_CHECKING:
-    import ssl as _typing_ssl
+    from ssl import SSLContext
 
 
 class TCPNetworkClient(AbstractNetworkClient[_T_SentPacket, _T_ReceivedPacket]):
@@ -75,7 +75,7 @@ def __init__(
         *,
         connect_timeout: float | None = ...,
         local_address: tuple[str, int] | None = ...,
-        ssl: _typing_ssl.SSLContext | bool | None = ...,
+        ssl: SSLContext | bool | None = ...,
         server_hostname: str | None = ...,
         ssl_handshake_timeout: float | None = ...,
         ssl_shutdown_timeout: float | None = ...,
@@ -93,7 +93,7 @@ def __init__(
         /,
         protocol: StreamProtocol[_T_SentPacket, _T_ReceivedPacket],
         *,
-        ssl: _typing_ssl.SSLContext | bool | None = ...,
+        ssl: SSLContext | bool | None = ...,
         server_hostname: str | None = ...,
         ssl_handshake_timeout: float | None = ...,
         ssl_shutdown_timeout: float | None = ...,
@@ -110,7 +110,7 @@ def __init__(
         /,
         protocol: StreamProtocol[_T_SentPacket, _T_ReceivedPacket],
         *,
-        ssl: _typing_ssl.SSLContext | bool | None = None,
+        ssl: SSLContext | bool | None = None,
         server_hostname: str | None = None,
         ssl_handshake_timeout: float | None = None,
         ssl_shutdown_timeout: float | None = None,

diff --git a/src/easynetwork/lowlevel/api_async/backend/abc.py b/src/easynetwork/lowlevel/api_async/backend/abc.py
@@ -34,7 +34,7 @@
 from collections.abc import Awaitable, Callable, Coroutine, Mapping, Sequence
 from contextlib import AbstractContextManager
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, Generic, NoReturn, ParamSpec, Protocol, Self, TypeVar, TypeVarTuple
+from typing import TYPE_CHECKING, Any, Generic, NoReturn, ParamSpec, Protocol, Self, TypeVar, TypeVarTuple, Unpack
 
 if TYPE_CHECKING:
     import concurrent.futures
@@ -451,9 +451,9 @@ async def __aexit__(
     @abstractmethod
     def start_soon(
         self,
-        coro_func: Callable[[*_T_PosArgs], Coroutine[Any, Any, _T]],
+        coro_func: Callable[[Unpack[_T_PosArgs]], Coroutine[Any, Any, _T]],
         /,
-        *args: *_T_PosArgs,
+        *args: Unpack[_T_PosArgs],
         name: str | None = ...,
     ) -> None:
         """
@@ -470,9 +470,9 @@ def start_soon(
     @abstractmethod
     async def start(
         self,
-        coro_func: Callable[[*_T_PosArgs], Coroutine[Any, Any, _T]],
+        coro_func: Callable[[Unpack[_T_PosArgs]], Coroutine[Any, Any, _T]],
         /,
-        *args: *_T_PosArgs,
+        *args: Unpack[_T_PosArgs],
         name: str | None = ...,
     ) -> Task[_T]:
         """
@@ -625,8 +625,8 @@ class AsyncBackend(metaclass=ABCMeta):
     @abstractmethod
     def bootstrap(
         self,
-        coro_func: Callable[[*_T_PosArgs], Coroutine[Any, Any, _T]],
-        *args: *_T_PosArgs,
+        coro_func: Callable[[Unpack[_T_PosArgs]], Coroutine[Any, Any, _T]],
+        *args: Unpack[_T_PosArgs],
         runner_options: Mapping[str, Any] | None = ...,
     ) -> _T:
         """