Review and update docstrings for Admin class (#551)

# Improve Admin API Documentation

## Summary

This PR comprehensively reviews and updates all docstrings in the Admin
class and its child resource classes (ProjectResource, ApiKeyResource,
OrganizationResource) to ensure they follow RST formatting standards and
include comprehensive code-block usage examples. All docstrings now have
proper whitespace formatting around code blocks to ensure Sphinx renders
them correctly.

## Problem

The Admin API documentation had several issues:
- Some methods were missing code-block usage examples
- Alias methods (`get`, `describe`) lacked examples showing how to use
them
- Code blocks were missing empty lines after them, which can cause
Sphinx rendering issues
- Some examples had syntax errors (missing commas)
- The `__init__` method lacked usage examples showing different
initialization patterns

## Solution

- **Added comprehensive examples**: All methods now include code-block
examples demonstrating different ways to use each function
- **Fixed formatting**: Added empty lines after all code blocks to
ensure proper Sphinx rendering
- **Enhanced alias methods**: Added examples to `get()` and `describe()`
methods in all resource classes
- **Fixed syntax errors**: Corrected missing comma in project creation
example
- **Improved initialization docs**: Added examples showing environment
variable usage, explicit credentials, and additional headers

## User-Facing Impact

Users will now have:
- **Better discoverability**: Clear examples for every Admin API method,
including aliases
- **Multiple usage patterns**: Examples showing different ways to
accomplish the same task (e.g., using `project_id` vs `name`)
- **Properly rendered docs**: Code blocks will render correctly in
Sphinx-generated documentation
- **Complete coverage**: No methods are left without examples, making
the API easier to learn and use

## Usage Examples

### Before
```python
# Alias methods had no examples
admin.project.get(project_id="...")  # No documentation example
```

### After
```python
# Now includes comprehensive examples
admin.project.get(project_id="42ca341d-43bf-47cb-9f27-e645dbfabea6")
# Shows both project_id and name usage patterns
```

### Initialization Examples
```python
# Environment variables
admin = Admin()  # Reads from PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET

# Explicit credentials
admin = Admin(
    client_id="your-client-id",
    client_secret="your-client-secret"
)

# With additional headers
admin = Admin(
    client_id="your-client-id",
    client_secret="your-client-secret",
    additional_headers={"X-Custom-Header": "value"}
)
```

## Breaking Changes

None. This is a documentation-only change that does not affect any API
functionality or behavior.

Author: jhamon

pinecone/admin/admin.py

@@ -58,6 +58,46 @@ def __init__(
           dictionary of key-value pairs. This is primarily used for internal testing
           purposes.
         :type additional_headers: Optional[dict[str, str]]
+
+        Examples
+        --------
+
+        .. code-block:: python
+            :caption: Initialize Admin using environment variables
+
+            import os
+            from pinecone import Admin
+
+            # Set environment variables
+            os.environ["PINECONE_CLIENT_ID"] = "your-client-id"
+            os.environ["PINECONE_CLIENT_SECRET"] = "your-client-secret"
+
+            # Initialize Admin (reads from environment variables)
+            admin = Admin()
+
+        .. code-block:: python
+            :caption: Initialize Admin with explicit credentials
+
+            from pinecone import Admin
+
+            # Initialize Admin with explicit credentials
+            admin = Admin(
+                client_id="your-client-id",
+                client_secret="your-client-secret"
+            )
+
+        .. code-block:: python
+            :caption: Initialize Admin with additional headers
+
+            from pinecone import Admin
+
+            # Initialize Admin with additional headers for testing
+            admin = Admin(
+                client_id="your-client-id",
+                client_secret="your-client-secret",
+                additional_headers={"X-Custom-Header": "value"}
+            )
+
         """
 
         if client_id is not None:
@@ -149,7 +189,7 @@ def project(self):
 
             # Create a project with no quota for pod indexes
             admin.project.create(
-                name="my-project"
+                name="my-project",
                 max_pods=0
             )
 
@@ -169,6 +209,7 @@ def project(self):
             admin = Admin()
             project = admin.project.get(name="my-project")
             admin.project.delete(project_id=project.id)
+
         """
         if self._project is None:
             from pinecone.admin.resources import ProjectResource

pinecone/admin/resources/api_key.py

@@ -67,6 +67,7 @@ def list(self, project_id: str):
                 print(api_key.name)
                 print(api_key.description)
                 print(api_key.roles)
+
         """
         return self._api_keys_api.list_project_api_keys(project_id=project_id)
 
@@ -108,12 +109,54 @@ def fetch(self, api_key_id: str):
 
     @require_kwargs
     def get(self, api_key_id: str):
-        """Alias for :func:`fetch`"""
+        """Alias for :func:`fetch`
+
+        Examples
+        --------
+
+        .. code-block:: python
+            :caption: Get an API key by api_key_id
+
+            from pinecone import Admin
+
+            # Credentials read from PINECONE_CLIENT_ID and
+            # PINECONE_CLIENT_SECRET environment variables
+            admin = Admin()
+
+            api_key = admin.api_key.get(api_key_id='my-api-key-id')
+            print(api_key.id)
+            print(api_key.name)
+            print(api_key.description)
+            print(api_key.roles)
+            print(api_key.created_at)
+
+        """
         return self.fetch(api_key_id=api_key_id)
 
     @require_kwargs
     def describe(self, api_key_id: str):
-        """Alias for :func:`fetch`"""
+        """Alias for :func:`fetch`
+
+        Examples
+        --------
+
+        .. code-block:: python
+            :caption: Describe an API key by api_key_id
+
+            from pinecone import Admin
+
+            # Credentials read from PINECONE_CLIENT_ID and
+            # PINECONE_CLIENT_SECRET environment variables
+            admin = Admin()
+
+            api_key = admin.api_key.describe(api_key_id='my-api-key-id')
+            print(api_key.id)
+            print(api_key.name)
+            print(api_key.description)
+            print(api_key.roles)
+            print(api_key.created_at)
+
+        """
         return self.fetch(api_key_id=api_key_id)
 
     @require_kwargs
@@ -204,6 +247,7 @@ def create(
 
             api_key_value = api_key_response.value
             print(api_key_value)
+
         """
         args = [("name", name), ("description", description), ("roles", roles)]
         create_api_key_request = CreateAPIKeyRequest(**parse_non_empty_args(args))

pinecone/admin/resources/organization.py

@@ -64,6 +64,7 @@ def list(self):
                 print(organization.name)
                 print(organization.plan)
                 print(organization.payment_status)
+
         """
         return self._organizations_api.list_organizations()
 
@@ -125,6 +126,7 @@ def get(self, organization_id: str):
             )
             print(organization.id)
             print(organization.name)
+
         """
         return self.fetch(organization_id=organization_id)
 
@@ -150,6 +152,7 @@ def describe(self, organization_id: str):
             )
             print(organization.id)
             print(organization.name)
+
         """
         return self.fetch(organization_id=organization_id)
 

pinecone/admin/resources/project.py

@@ -74,6 +74,7 @@ def list(self):
                 print(project.name)
                 print(project.max_pods)
                 print(project.force_encryption_with_cmek)
+
         """
         return self._projects_api.list_projects()
 
@@ -129,6 +130,7 @@ def fetch(self, project_id: str | None = None, name: str | None = None):
             print(project.force_encryption_with_cmek)
             print(project.organization_id)
             print(project.created_at)
+
         """
         if project_id is not None and name is not None:
             raise ValueError("Either project_id or name must be provided but not both")
@@ -174,6 +176,7 @@ def get(self, project_id: str | None = None, name: str | None = None):
             print(project.name)
             print(project.max_pods)
             print(project.force_encryption_with_cmek)
+
         """
         return self.fetch(project_id=project_id, name=name)
 
@@ -201,6 +204,7 @@ def describe(self, project_id: str | None = None, name: str | None = None):
             print(project.name)
             print(project.max_pods)
             print(project.force_encryption_with_cmek)
+
         """
         return self.fetch(project_id=project_id, name=name)
 
@@ -256,6 +260,7 @@ def exists(self, project_id: str | None = None, name: str | None = None):
                 print(f"Project {project_id} exists")
             else:
                 print(f"Project {project_id} does not exist")
+
         """
         if project_id is not None and name is not None:
             raise ValueError("Either project_id or name must be provided but not both")
@@ -453,6 +458,7 @@ def delete(
                 print("Project deleted successfully")
             else:
                 print("Project deletion failed")
+
         """
         project = self.get(project_id=project_id)
 

pinecone/inference/inference.py

@@ -194,6 +194,31 @@ def embed(
             #     usage={'total_tokens': 6}
             # )
 
+        You can also use a single string input:
+
+        .. code-block:: python
+
+            from pinecone import Pinecone
+
+            pc = Pinecone()
+            output = pc.inference.embed(
+                model="text-embedding-3-small",
+                inputs="Hello, world!"
+            )
+
+        Or use the EmbedModel enum:
+
+        .. code-block:: python
+
+            from pinecone import Pinecone
+            from pinecone.inference import EmbedModel
+
+            pc = Pinecone()
+            outputs = pc.inference.embed(
+                model=EmbedModel.TEXT_EMBEDDING_3_SMALL,
+                inputs=["Document 1", "Document 2"]
+            )
+
         """
         request_body = InferenceRequestBuilder.embed_request(
             model=model, inputs=inputs, parameters=parameters
@@ -235,8 +260,7 @@ def rerank(
           relevance, with the first being the most relevant. The ``index`` field can be used to locate the document
           relative to the list of documents specified in the request. Each document contains a ``score`` key
           representing how close the document relates to the query.
-
-        Example:
+        :rtype: RerankResult
 
         .. code-block:: python
 
@@ -275,6 +299,38 @@ def rerank(
             #     usage={'rerank_units': 1}
             # )
 
+        You can also use document dictionaries with custom fields:
+
+        .. code-block:: python
+
+            from pinecone import Pinecone
+
+            pc = Pinecone()
+            result = pc.inference.rerank(
+                model="pinecone-rerank-v0",
+                query="What is machine learning?",
+                documents=[
+                    {"text": "Machine learning is a subset of AI.", "category": "tech"},
+                    {"text": "Cooking recipes for pasta.", "category": "food"},
+                ],
+                rank_fields=["text"],
+                top_n=1
+            )
+
+        Or use the RerankModel enum:
+
+        .. code-block:: python
+
+            from pinecone import Pinecone
+            from pinecone.inference import RerankModel
+
+            pc = Pinecone()
+            result = pc.inference.rerank(
+                model=RerankModel.PINECONE_RERANK_V0,
+                query="Your query here",
+                documents=["doc1", "doc2", "doc3"]
+            )
+
         """
         rerank_request = InferenceRequestBuilder.rerank(
             model=model,
@@ -302,8 +358,7 @@ def list_models(
         :type vector_type: str, optional
 
         :return: A list of models.
-
-        Example:
+        :rtype: ModelInfoList
 
         .. code-block:: python
 
@@ -339,8 +394,6 @@ def get_model(self, model_name: str) -> "ModelInfo":
         :return: A ModelInfo object.
         :rtype: ModelInfo
 
-        Example:
-
         .. code-block:: python
 
             from pinecone import Pinecone
@@ -371,5 +424,6 @@ def get_model(self, model_name: str) -> "ModelInfo":
             #     "provider_name": "Pinecone",
             #     "supported_metrics": []
             # }
+
         """
         return self.model.get(model_name=model_name)