Update Pinecone class docstrings (#550)

# Improve Docstring Documentation and Remove Redundant Interface

## Summary

This PR comprehensively reviews and updates all method docstrings in the
`Pinecone` class and underlying interface classes to ensure they use
proper RST syntax, include code-block usage examples, and have correct
whitespace formatting for Sphinx rendering. Additionally, this PR
removes the redundant `LegacyPineconeDBControlInterface` class that was
creating maintenance overhead and sync risks.

## Problem

1. **Incomplete Documentation**: Many methods in the `Pinecone` class
lacked comprehensive docstrings with usage examples, making it difficult
for users to understand how to use the SDK effectively.

2. **Inconsistent Formatting**: Some docstrings used different formats
(e.g., `Args:` vs `:param:`), and code-block examples lacked proper
whitespace formatting required for Sphinx to render correctly.

3. **Redundant Interface**: The `LegacyPineconeDBControlInterface` class
served primarily as a docstring container, creating duplication and the
risk of documentation falling out of sync with implementations.

4. **Unrealistic Examples**: Some code examples (particularly in the
`inference` property) used placeholder content that didn't demonstrate
real-world usage patterns.

## Solution

1. **Added Comprehensive Docstrings**: Added complete RST-formatted
docstrings with code-block examples to all `Pinecone` class methods that
were missing them, including:
- Index management methods (`create_index`, `delete_index`,
`list_indexes`, `describe_index`, `has_index`, `configure_index`)
- Collection methods (`create_collection`, `list_collections`,
`delete_collection`, `describe_collection`)
- Backup and restore job methods (`create_backup`, `list_backups`,
`describe_backup`, `delete_backup`, `list_restore_jobs`,
`describe_restore_job`)
   - Index instantiation methods (`Index`, `IndexAsyncio`)
   - Properties (`inference`, `db`)

2. **Standardized RST Format**: Converted all docstrings to use
consistent RST syntax with `:param:` and `:type:` directives instead of
mixed formats.

3. **Fixed Code-Block Formatting**: Ensured all code-block examples have
proper whitespace (empty line after code blocks) for correct Sphinx
rendering.

4. **Improved Examples**: Updated examples to be more realistic and
demonstrate actual usage patterns, including:
- Updated the `inference` property example to show realistic embedding
and reranking operations with actual document content
   - Fixed syntax errors in import statements within docstring examples
- Added multiple usage patterns where appropriate (e.g., different ways
to create indexes)

5. **Removed Redundant Interface**: Deleted
`LegacyPineconeDBControlInterface` since:
- All docstrings now live in the `Pinecone` class implementation (single
source of truth)
- The interface was only used by `Pinecone` and provided no additional
value
   - Eliminates the risk of documentation falling out of sync

6. **Updated Interface Classes**: Enhanced docstrings in
`IndexInterface` with proper RST formatting and added missing code-block
examples (e.g., `upsert_from_dataframe`).

## User-Facing Impact

### Positive Changes

- **Better Documentation**: Users now have comprehensive, well-formatted
documentation with realistic examples for all `Pinecone` class methods
- **Improved IDE Experience**: Better docstrings improve autocomplete
and inline help in IDEs
- **Consistent Formatting**: All documentation follows the same RST
format, making it easier to read and understand
- **Real-World Examples**: Code examples now demonstrate actual usage
patterns that users can directly adapt

### Breaking Changes

**None** - This is a documentation-only change. All method signatures
and behavior remain unchanged.

## Usage Examples

### Before

```python
# Minimal or missing docstrings
pc = Pinecone()
pc.create_index(...)  # No clear guidance on usage
```

### After

```python
# Comprehensive documentation with examples
from pinecone import Pinecone, ServerlessSpec, CloudProvider, AwsRegion, Metric

pc = Pinecone()

# Clear examples showing different ways to create indexes
pc.create_index(
    name="my_index",
    dimension=512,
    metric=Metric.COSINE,
    spec=ServerlessSpec(
        cloud=CloudProvider.AWS,
        region=AwsRegion.US_WEST_2
    )
)
```

### Improved Inference Example

The `inference` property now shows realistic usage:

```python
from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")

# Generate embeddings for text
embeddings = pc.inference.embed(
    model="multilingual-e5-large",
    inputs=["Disease prevention", "Immune system health"]
)

# Rerank documents based on query relevance
reranked = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="Disease prevention",
    documents=[
        "Rich in vitamin C and other antioxidants, apples contribute to immune health...",
        "The high fiber content in apples can also help regulate blood sugar levels...",
        # ... more realistic examples
    ],
    top_n=2,
    rank_fields=["text"]
)
```

## Technical Details

- All docstrings now use RST syntax consistently
- Code-block examples include proper whitespace formatting (empty line
after code blocks)
- Fixed syntax errors in docstring examples (e.g., import statements)
- Removed `LegacyPineconeDBControlInterface` class and its file
- Updated `Pinecone` class to no longer inherit from the removed
interface
- Enhanced `IndexInterface` docstrings with proper formatting and
examples

Author: jhamon

pinecone/db_data/interfaces.py

@@ -244,11 +244,38 @@ def upsert_from_dataframe(
     ):
         """Upserts a dataframe into the index.
 
-        Args:
-            df: A pandas dataframe with the following columns: id, values, sparse_values, and metadata.
-            namespace: The namespace to upsert into.
-            batch_size: The number of rows to upsert in a single batch.
-            show_progress: Whether to show a progress bar.
+        :param df: A pandas dataframe with the following columns: id, values, sparse_values, and metadata.
+        :type df: pandas.DataFrame
+        :param namespace: The namespace to upsert into.
+        :type namespace: str, optional
+        :param batch_size: The number of rows to upsert in a single batch.
+        :type batch_size: int, optional
+        :param show_progress: Whether to show a progress bar.
+        :type show_progress: bool, optional
+
+        .. code-block:: python
+
+            import pandas as pd
+            from pinecone import Pinecone
+
+            pc = Pinecone()
+            idx = pc.Index(host="your-index-host")
+
+            # Create a dataframe with vector data
+            df = pd.DataFrame({
+                'id': ['id1', 'id2', 'id3'],
+                'values': [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]],
+                'metadata': [{'key': 'value1'}, {'key': 'value2'}, {'key': 'value3'}]
+            })
+
+            # Upsert the dataframe
+            idx.upsert_from_dataframe(
+                df=df,
+                namespace="my-namespace",
+                batch_size=100,
+                show_progress=True
+            )
+
         """
         pass
 
@@ -276,7 +303,7 @@ def upsert_records(self, namespace: str, records: list[dict]) -> UpsertResponse:
                 Pinecone,
                 CloudProvider,
                 AwsRegion,
-                EmbedModel
+                EmbedModel,
                 IndexEmbed
             )
 
@@ -382,7 +409,7 @@ def search(
                 Pinecone,
                 CloudProvider,
                 AwsRegion,
-                EmbedModel
+                EmbedModel,
                 IndexEmbed
             )