Make docs RST format and add more details for public facing methods (#29)

* Make docs RST format and add more details for public facing methods

* remove rtype / returns for None

* Update src/dataverse_sdk/client.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Tim Pellissier <tpellissier@microsoft.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

src/dataverse_sdk/__init__.py

@@ -1,3 +1,45 @@
+"""
+Microsoft Dataverse SDK for Python.
+
+This package provides a high-level Python client for interacting with Microsoft Dataverse
+environments through the Web API. It supports CRUD operations, SQL queries, table metadata
+management, and file uploads with Azure Identity authentication.
+
+Key Features:
+    - OData CRUD operations (create, read, update, delete)
+    - SQL query support via Web API
+    - Table metadata operations (create, inspect, delete custom tables)
+    - File column upload capabilities
+    - Pandas integration for DataFrame-based operations
+    - Azure Identity credential support
+
+.. note::
+    This SDK requires Azure Identity credentials for authentication. See the
+    `Azure Identity documentation <https://learn.microsoft.com/python/api/overview/azure/identity-readme>`_
+    for supported credential types.
+
+Example:
+    Basic client initialization and usage::
+
+        from azure.identity import DefaultAzureCredential
+        from dataverse_sdk import DataverseClient
+
+        credential = DefaultAzureCredential()
+        client = DataverseClient(
+            "https://org.crm.dynamics.com",
+            credential
+        )
+
+        # Create a record
+        account_id = client.create("account", {"name": "Contoso"})[0]
+
+        # Query records
+        accounts = client.get("account", filter="name eq 'Contoso'")
+        for batch in accounts:
+            for record in batch:
+                print(record["name"])
+"""
+
 from .__version__ import __version__
 from .client import DataverseClient
 

src/dataverse_sdk/auth.py

@@ -7,12 +7,26 @@
 
 @dataclass
 class TokenPair:
+    """
+    Container for an OAuth2 access token and its associated resource scope.
+
+    :param resource: The OAuth2 scope/resource for which the token was acquired.
+    :type resource: str
+    :param access_token: The access token string.
+    :type access_token: str
+    """
     resource: str
     access_token: str
 
 
 class AuthManager:
-    """Azure Identity-based authentication helper for Dataverse."""
+    """
+    Azure Identity-based authentication manager for Dataverse.
+
+    :param credential: Azure Identity credential implementation.
+    :type credential: ~azure.core.credentials.TokenCredential
+    :raises TypeError: If ``credential`` does not implement :class:`~azure.core.credentials.TokenCredential`.
+    """
 
     def __init__(self, credential: TokenCredential) -> None:
         if not isinstance(credential, TokenCredential):
@@ -22,6 +36,14 @@ def __init__(self, credential: TokenCredential) -> None:
         self.credential: TokenCredential = credential
 
     def acquire_token(self, scope: str) -> TokenPair:
-        """Acquire an access token for the given scope using Azure Identity."""
+        """
+        Acquire an access token for the specified OAuth2 scope.
+
+        :param scope: OAuth2 scope string, typically ``"https://<org>.crm.dynamics.com/.default"``.
+        :type scope: str
+        :return: Token pair containing the scope and access token.
+        :rtype: ~dataverse_sdk.auth.TokenPair
+        :raises ~azure.core.exceptions.ClientAuthenticationError: If token acquisition fails.
+        """
         token = self.credential.get_token(scope)
         return TokenPair(resource=scope, access_token=token.token)