updated documentation

docs/api-reference/auth.md

@@ -0,0 +1,6 @@
+::: aiosalesforce.auth
+    options:
+        members:
+        - Auth
+        - SoapLogin
+        - ClientCredentialsFlow

docs/api-reference/client.md

@@ -0,0 +1 @@
+::: aiosalesforce.client

docs/api-reference/events.md

@@ -1 +1,15 @@
 ::: aiosalesforce.events
+    options:
+        members:
+        - EventBus
+        - Event
+        - RequestEvent
+        - RetryEvent
+        - ResponseEvent
+        - RestApiCallConsumptionEvent
+        - BulkApiBatchConsumptionEvent
+
+::: aiosalesforce.events.events
+    options:
+        members:
+        - ResponseMixin

docs/api-reference/retries.md

@@ -1 +1,6 @@
 ::: aiosalesforce.retries
+
+::: aiosalesforce.retries.policy
+    options:
+        members:
+        - RetryContext

docs/api-reference/sobject.md

@@ -0,0 +1 @@
+::: aiosalesforce.sobject

docs/api-reference/utils.md

@@ -0,0 +1 @@
+::: aiosalesforce.utils

docs/documentation/authentication.md

@@ -4,7 +4,7 @@ Before you can make requests to the Salesforce API, you need to authenticate
 In `aiosalesforce` authentication is a dependency you provide
 to the [`Salesforce` client](/aiosalesforce/documentation/client).
 The typical usage pattern looks like this
-(using the `SoapLogin` authentication method as an example):
+(using the [`SoapLogin`](#soap-login) authentication method as an example):
 
 ```python
 import asyncio
@@ -85,12 +85,15 @@ auth = ClientCredentials(
 
 ## Custom Authentication
 
-You can create a custom authentication class by subclassing the `Auth` class and
-implementing the `_acquire_new_access_token` and
+You can create a custom authentication class by subclassing the
+[`Auth`](/aiosalesforce/api-reference/auth/#aiosalesforce.auth.Auth)
+class and implementing the `_acquire_new_access_token` and
 (optionally) the `_refresh_access_token` methods.
 
 When implementing custom authentication, you are responsible for emitting appropriate
-events using the provided `EventBus` instance.
+events using the provided
+[`EventBus`](/aiosalesforce/api-reference/events/#aiosalesforce.events.EventBus)
+instance.
 
 ```python
 from aiosalesforce.auth import Auth

mkdocs.yml

@@ -13,11 +13,13 @@ nav:
       - Authentication: documentation/authentication.md
       - Salesforce client: documentation/client.md
   - API Reference:
-      - Salesforce Client: api-reference/salesforce-client.md
-      - Sobject Client: api-reference/sobject-client.md
+      - Authentication: api-reference/auth.md
+      - Salesforce Client: api-reference/client.md
+      - Sobject Client: api-reference/sobject.md
       - Events: api-reference/events.md
       - Retries: api-reference/retries.md
       - Exceptions: api-reference/exceptions.md
+      - Utilities: api-reference/utils.md
 
 theme:
   name: material
@@ -57,8 +59,9 @@ plugins:
         python:
           options:
             show_source: true
+            show_root_toc_entry: false
             docstring_style: "numpy"
-            show_root_heading: true
+            members_order: "source"
 
 extra:
   social:

src/aiosalesforce/auth/base.py

@@ -12,6 +12,11 @@
 
 
 class Auth(ABC):
+    """
+    Base class for Salesforce authentication.
+
+    """
+
     def __init__(self) -> None:
         self.__access_token: str | None = None
         self.__lock = asyncio.Lock()

src/aiosalesforce/auth/client_credentials_flow.py

@@ -12,6 +12,13 @@ class ClientCredentialsFlow(Auth):
 
     https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_client_credentials_flow.htm&type=5
 
+    Parameters
+    ----------
+    client_id : str
+        Client ID.
+    client_secret : str
+        Client secret.
+
     """
 
     def __init__(self, client_id: str, client_secret: str) -> None:

src/aiosalesforce/auth/soap.py

@@ -15,6 +15,15 @@ class SoapLogin(Auth):
 
     https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_login.htm
 
+    Parameters
+    ----------
+    username : str
+        Username.
+    password : str
+        Password.
+    security_token : str
+        Security token.
+
     """
 
     def __init__(

src/aiosalesforce/client.py

@@ -209,7 +209,7 @@ async def query(
         ----------
         query : str
             SOQL query.
-        include_all_records : bool, optional
+        include_all_records : bool, default False
             If True, includes all (active/deleted/archived) records.
 
         Returns

src/aiosalesforce/events/event_bus.py

@@ -27,9 +27,27 @@ def __init__(self, callbacks: list[CallbackType] | None = None) -> None:
             self.subscribe_callback(callback)
 
     def subscribe_callback(self, callback: CallbackType) -> None:
+        """
+        Subscribe a callback to the event bus.
+
+        Parameters
+        ----------
+        callback : CallbackType
+            Function to be called when an event is published.
+
+        """
         self._callbacks.add(callback)
 
     def unsubscribe_callback(self, callback: CallbackType) -> None:
+        """
+        Unsubscribe a callback from the event bus.
+
+        Parameters
+        ----------
+        callback : CallbackType
+            Function to be unsubscribed.
+
+        """
         self._callbacks.discard(callback)
 
     @staticmethod

src/aiosalesforce/events/events.py

@@ -8,14 +8,18 @@
 
 
 class ResponseMixin:
+    """Mixin class providing properties for events which may have response."""
+
     response: Response | None
 
     @property
     def consumed(self) -> int | None:
+        """Number of API calls consumed in the current 24-hour period."""
         return self.__api_usage[0]
 
     @property
     def remaining(self) -> int | None:
+        """Number of API calls remaining in the current 24-hour period."""
         return self.__api_usage[1]
 
     @cached_property
@@ -37,6 +41,8 @@ def __api_usage(self) -> tuple[int, int] | tuple[None, None]:
 
 @dataclass
 class Event:
+    """Base class for all events."""
+
     type: Literal[
         "request",
         "response",

src/aiosalesforce/retries/policy.py

@@ -16,6 +16,20 @@ class RetryCounts(TypedDict):
 
 
 class RetryContext:
+    """
+    Context for retrying a particular request.
+
+    Parameters
+    ----------
+    response_rules : list[ResponseRule]
+        Rules for retrying requests based on their responses.
+    exception_rules : list[ExceptionRule]
+        Rules for retrying requests after an exception.
+    max_retries : int
+        Maximum total number of retries.
+
+    """
+
     __slots__ = (
         "response_rules",
         "exception_rules",
@@ -52,6 +66,20 @@ def __init__(
         }
 
     async def should_retry(self, value: Response | Exception) -> bool:
+        """
+        Determine if the request should be retried.
+
+        Parameters
+        ----------
+        value : Response | Exception
+            Response or Exception from the request.
+
+        Returns
+        -------
+        bool
+            True if the request should be retried, False otherwise.
+
+        """
         if (
             self.retry_count["total"] >= self.max_retries
             or time.time() - self.start > self.timeout

src/aiosalesforce/retries/rules.py

@@ -36,6 +36,20 @@ def __init__(
         self.max_retries = max_retries
 
     async def should_retry(self, response: Response) -> bool:
+        """
+        Determine if the request should be retried.
+
+        Parameters
+        ----------
+        response : Response
+            Response from the request.
+
+        Returns
+        -------
+        bool
+            True if the request should be retried, False otherwise.
+
+        """
         if inspect.iscoroutinefunction(self.func):
             return await self.func(response)
         else:
@@ -87,6 +101,20 @@ def __init__(
         self.max_retries = max_retries
 
     async def should_retry(self, exc: E) -> bool:
+        """
+        Determine if the request should be retried.
+
+        Parameters
+        ----------
+        exc : Exception
+            Exception from the request.
+
+        Returns
+        -------
+        bool
+            True if the request should be retried, False otherwise.
+
+        """
         if not isinstance(exc, self.exception_type):
             return False
         if inspect.iscoroutinefunction(self.func):

src/aiosalesforce/sobject.py

@@ -97,7 +97,8 @@ async def get(
         external_id_field : str, optional
             External ID field name, by default None.
         fields : list[str], optional
-            Fields to get for the record, by default None (all fields).
+            Fields to get for the record.
+            By default returns all fields.
 
         Returns
         -------
@@ -164,7 +165,8 @@ async def delete(
         id_ : str
             Salesforce record ID or external ID (if external_id_field is provided).
         external_id_field : str, optional
-            External ID field name, by default None.
+            External ID field name.
+            If not provided, id_ is treated as a record ID.
 
         """
         url = f"{self.base_url}/{sobject}"
@@ -198,7 +200,7 @@ async def upsert(
         data : dict | str | bytes | bytearray
             Data to upsert the record with.
             Either a dict or a JSON string/bytes representing a dict.
-        validate : bool, optional
+        validate : bool, default True
             If True, validates the request and removes the external ID field
             from the data if it's present. By default True.
             The reason for this is that Salesforce does not allow

src/aiosalesforce/utils.py

@@ -92,7 +92,7 @@ def _sanitize_soql_query_parameter(  # noqa: PLR0911
     ----------
     value : str
         Value to be sanitized.
-    like : bool, optional
+    like : bool, default True
         Whether the string is to be used in a LIKE clause, by default False.
         When True, % and _ characters are escaped and
         the returned string is not enclosed in single quotes.