Adjusting documentation

Author: apetenchea

.github/workflows/docs.yaml

@@ -24,5 +24,5 @@ jobs:
       - name: Install dependencies
         run: pip install .[dev]
 
-      - name: Generate Sphinx HTML
-        run: python -m sphinx -b html -W docs docs/_build
+      - name: Run Sphinx doctest
+        run: python -m sphinx -b doctest docs docs/_build

arangoasync/http.py

@@ -15,19 +15,31 @@
 
 class HTTPClient(ABC):  # pragma: no cover
     """Abstract base class for HTTP clients.
+
     Custom HTTP clients should inherit from this class.
+
+    Example:
+        .. code-block:: python
+
+            class MyCustomHTTPClient(HTTPClient):
+                def create_session(self, host):
+                    pass
+                async def send_request(self, session, request):
+                    pass
     """
 
     @abstractmethod
     def create_session(self, host: str) -> Any:
         """Return a new session given the base host URL.
 
-        This method must be overridden by the user.
+        Note:
+            This method must be overridden by the user.
+
+        Args:
+            host (str): ArangoDB host URL.
 
-        :param host: ArangoDB host URL.
-        :type host: str
-        :returns: Requests session object.
-        :rtype: Any
+        Returns:
+            Requests session object.
         """
         raise NotImplementedError
 
@@ -39,37 +51,36 @@ async def send_request(
     ) -> Response:
         """Send an HTTP request.
 
-        This method must be overridden by the user.
+        Note:
+            This method must be overridden by the user.
 
-        :param session: Session object.
-        :type session: Any
-        :param request: HTTP request.
-        :type request: arangoasync.request.Request
-        :returns: HTTP response.
-        :rtype: arangoasync.response.Response
+        Args:
+            session (Any): Client session object.
+            request (Request): HTTP request.
+
+        Returns:
+            Response: HTTP response.
         """
         raise NotImplementedError
 
 
 class AioHTTPClient(HTTPClient):
-    """HTTP client implemented on top of [aiohttp](https://docs.aiohttp.org/en/stable/).
-
-    :param connector: Supports connection pooling.
-        By default, 100 simultaneous connections are supported, with a 60-second timeout
-        for connection reusing after release.
-    :type connector: aiohttp.BaseConnector | None
-    :param timeout: Timeout settings.
-        300s total timeout by default for a complete request/response operation.
-    :type timeout: aiohttp.ClientTimeout | None
-    :param read_bufsize: Size of read buffer (64KB default).
-    :type read_bufsize: int
-    :param auth: HTTP authentication helper.
-        Should be used for specifying authorization data in client API.
-    :type auth: aiohttp.BasicAuth | None
-    :param compression_threshold: Will compress requests to the server if
-        the size of the request body (in bytes) is at least the value of this
-        option.
-    :type compression_threshold: int
+    """HTTP client implemented on top of aiohttp_.
+
+    Args:
+        connector (aiohttp.BaseConnector | None): Supports connection pooling.
+            By default, 100 simultaneous connections are supported, with a 60-second
+            timeout for connection reusing after release.
+        timeout (aiohttp.ClientTimeout | None): Client timeout settings.
+            300s total timeout by default for a complete request/response operation.
+        read_bufsize (int): Size of read buffer (64KB default).
+        auth (aiohttp.BasicAuth | None): HTTP authentication helper.
+            Should be used for specifying authorization data in client API.
+        compression_threshold (int): Will compress requests to the server if the size
+            of the request body (in bytes) is at least the value of this option.
+
+    .. _aiohttp:
+        https://docs.aiohttp.org/en/stable/
     """
 
     def __init__(
@@ -95,11 +106,12 @@ def __init__(
     def create_session(self, host: str) -> ClientSession:
         """Return a new session given the base host URL.
 
-        :param host: ArangoDB host URL. Typically, the address and port of a coordinator
-            (e.g. "http://127.0.0.1:8529").
-        :type host: str
-        :returns: Session object.
-        :rtype: aiohttp.ClientSession
+        Args:
+            host (str): ArangoDB host URL. Must not include any paths. Typically, this
+                is the address and port of a coordinator (e.g. "http://127.0.0.1:8529").
+
+        Returns:
+            aiohttp.ClientSession: Session object, used to send future requests.
         """
         return ClientSession(
             base_url=host,
@@ -116,12 +128,12 @@ async def send_request(
     ) -> Response:
         """Send an HTTP request.
 
-        :param session: Session object.
-        :type session: aiohttp.ClientSession
-        :param request: HTTP request.
-        :type request: arangoasync.request.Request
-        :returns: HTTP response.
-        :rtype: arangoasync.response.Response
+        Args:
+            session (aiohttp.ClientSession): Session object used to make the request.
+            request (Request): HTTP request.
+
+        Returns:
+            Response: HTTP response.
         """
         method = request.method
         endpoint = request.endpoint

arangoasync/request.py

@@ -11,7 +11,7 @@
 
 
 class Method(Enum):
-    """HTTP methods."""
+    """HTTP methods enum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"""
 
     GET = auto()
     POST = auto()
@@ -25,31 +25,19 @@ class Method(Enum):
 class Request:
     """HTTP request.
 
-    :param method: HTTP method.
-    :type method: request.Method
-    :param endpoint: API endpoint.
-    :type endpoint: str
-    :param headers: Request headers.
-    :type headers: dict | None
-    :param params: URL parameters.
-    :type params: dict | None
-    :param data: Request payload.
-    :type data: Any
-    :param deserialize: Whether the response body should be deserialized.
-    :type deserialize: bool
-
-    :ivar method: HTTP method.
-    :vartype method: request.Method
-    :ivar endpoint: API endpoint, for example "_api/version".
-    :vartype endpoint: str
-    :ivar headers: Request headers.
-    :vartype headers: dict | None
-    :ivar params: URL (query) parameters.
-    :vartype params: dict | None
-    :ivar data: Request payload.
-    :vartype data: Any
-    :ivar deserialize: Whether the response body should be deserialized.
-    :vartype deserialize: bool
+    Args:
+        method (Method): HTTP method.
+        endpoint (str): API endpoint.
+        headers (dict | None): Request headers.
+        params (dict | None): URL parameters.
+        data (str | None): Request payload.
+
+    Attributes:
+        method (Method): HTTP method.
+        endpoint (str): API endpoint.
+        headers (dict | None): Request headers.
+        params (dict | None): URL parameters.
+        data (str | None): Request payload.
     """
 
     __slots__ = (
@@ -58,7 +46,6 @@ class Request:
         "headers",
         "params",
         "data",
-        "deserialize",
     )
 
     def __init__(
@@ -68,23 +55,22 @@ def __init__(
         headers: Optional[Headers] = None,
         params: Optional[Params] = None,
         data: Optional[str] = None,
-        deserialize: bool = True,
     ) -> None:
         self.method: Method = method
         self.endpoint: str = endpoint
         self.headers: Headers = self._normalize_headers(headers)
         self.params: Params = self._normalize_params(params)
         self.data: Optional[str] = data
-        self.deserialize: bool = deserialize
 
     @staticmethod
     def _normalize_headers(headers: Optional[Headers]) -> Headers:
         """Normalize request headers.
 
-        :param headers: Request headers.
-        :type headers: dict | None
-        :returns: Normalized request headers.
-        :rtype: dict
+        Parameters:
+            headers (dict | None): Request headers.
+
+        Returns:
+            dict: Normalized request headers.
         """
         driver_header = f"arangoasync/{__version__}"
         normalized_headers: Headers = {
@@ -103,10 +89,11 @@ def _normalize_headers(headers: Optional[Headers]) -> Headers:
     def _normalize_params(params: Optional[Params]) -> Params:
         """Normalize URL parameters.
 
-        :param params: URL parameters.
-        :type params: dict | None
-        :returns: Normalized URL parameters.
-        :rtype: dict
+        Parameters:
+            params (dict | None): URL parameters.
+
+        Returns:
+            dict: Normalized URL parameters.
         """
         normalized_params: Params = {}
 

arangoasync/response.py

@@ -11,39 +11,24 @@
 class Response:
     """HTTP response.
 
-    :param method: HTTP method.
-    :type method: request.Method
-    :param url: API URL.
-    :type url: str
-    :param headers: Response headers.
-    :type headers: dict | None
-    :param status_code: Response status code.
-    :type status_code: int
-    :param status_text: Response status text.
-    :type status_text: str
-    :param raw_body: Raw response body.
-    :type raw_body: str
+    Parameters:
+        method (Method): HTTP method.
+        url (str): API URL.
+        headers (dict | None): Response headers.
+        status_code (int): Response status code.
+        status_text (str): Response status text.
+        raw_body (bytes): Raw response body.
 
-    :ivar method: HTTP method.
-    :vartype method: request.Method
-    :ivar url: API URL.
-    :vartype url: str
-    :ivar headers: Response headers.
-    :vartype headers: dict | None
-    :ivar status_code: Response status code.
-    :vartype status_code: int
-    :ivar status_text: Response status text.
-    :vartype status_text: str
-    :ivar raw_body: Raw response body.
-    :vartype raw_body: str
-    :ivar body: Response body after processing.
-    :vartype body: Any
-    :ivar error_code: Error code from ArangoDB server.
-    :vartype error_code: int
-    :ivar error_message: Error message from ArangoDB server.
-    :vartype error_message: str
-    :ivar is_success: True if response status code was 2XX.
-    :vartype is_success: bool
+    Attributes:
+        method (Method): HTTP method.
+        url (str): API URL.
+        headers (dict | None): Response headers.
+        status_code (int): Response status code.
+        status_text (str): Response status text.
+        raw_body (bytes): Raw response body.
+        error_code (int | None): Error code from ArangoDB server.
+        error_message (str | None): Error message from ArangoDB server.
+        is_success (bool | None): True if response status code was 2XX.
     """
 
     __slots__ = (
@@ -52,7 +37,6 @@ class Response:
         "headers",
         "status_code",
         "status_text",
-        "body",
         "raw_body",
         "error_code",
         "error_message",
@@ -76,7 +60,6 @@ def __init__(
         self.raw_body: bytes = raw_body
 
         # Populated later
-        self.body: Optional[str] = None
         self.error_code: Optional[int] = None
         self.error_message: Optional[str] = None
         self.is_success: Optional[bool] = None

docs/conf.py

@@ -12,14 +12,20 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
 ]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 html_theme = "sphinx_rtd_theme"
 master_doc = "index"
 
 autodoc_member_order = "bysource"
+autodoc_typehints = "none"
 
 intersphinx_mapping = {
     "aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
 }
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_attr_annotations = True

docs/specs.rst

@@ -4,50 +4,11 @@ API Specification
 This page contains the specification for all classes and methods available in
 python-arango-async.
 
-.. _AioHTTPClient:
-
-AioHTTPClient
-=================
-
-.. autoclass:: arangoasync.http.AioHTTPClient
-    :members:
-
-.. _DefaultHTTPClient:
-
-DefaultHTTPClient
-=================
-
-.. autoclass:: arangoasync.http.DefaultHTTPClient
-    :members:
-
-.. _HTTPClient:
-
-HTTPClient
-==========
-
-.. autoclass:: arangoasync.http.HTTPClient
+.. automodule:: arangoasync.http
     :members:
 
-.. _Method:
-
-Method
-=======
-
-.. autoclass:: arangoasync.request.Method
+.. automodule:: arangoasync.request
     :members:
 
-.. _Request:
-
-Request
-=======
-
-.. autoclass:: arangoasync.request.Request
-    :members:
-
-.. _Response:
-
-Response
-========
-
-.. autoclass:: arangoasync.response.Response
+.. automodule:: arangoasync.response
     :members: