Sdk Documentation

Step 1: Generate API Reference

Use the sdk_docs.py script:

python plugins/sdk-lifecycle/skills/sdk-documentation/scripts/sdk_docs.py \
  --project-path "path/to/sdk" \
  --language "python|dotnet|typescript" \
  --output-dir "docs/" \
  --format "markdown|html"

The script will:

• Extract documentation from code
• Generate API reference pages
• Create usage guide templates
• Validate code examples
• Generate table of contents

Step 2: Complete Usage Guide

Fill in the generated templates:

README.md Structure

# SDK Name

Brief description of what the SDK does.

## Installation

\`\`\`bash
# Language-specific installation
\`\`\`

## Quick Start

\`\`\`language
# Minimal working example
\`\`\`

## Authentication

How to authenticate with the API.

## Core Concepts

Key concepts users need to understand.

## Usage Examples

### Example 1: Basic Operation
### Example 2: Advanced Feature

## Error Handling

How to handle errors.

## Configuration

Available configuration options.

## API Reference

Link to detailed API documentation.

## Troubleshooting

Common issues and solutions.

## Contributing

How to contribute to the SDK.

## License

License information.

API Reference Structure

# API Reference

## Client

### Constructor

### Methods

#### get_resource(resource_id)

**Description**: Get a resource by ID.

**Parameters**:
- `resource_id` (str): Resource identifier

**Returns**: Resource object

**Raises**:
- `ResourceNotFoundError`: If resource doesn't exist
- `AuthenticationError`: If authentication fails

**Example**:
\`\`\`python
resource = await client.get_resource("res-123")
print(resource.name)
\`\`\`

Step 3: Language-Specific Documentation

Python Documentation

Use docstrings throughout:

class Client:
    """
    Client for Infiquetra Service API.

    Args:
        api_key: API key for authentication
        base_url: Base URL of the API (default: https://api.example.com)
        timeout: Request timeout in seconds (default: 30.0)

    Example:
        ```python
        async with Client(api_key="your-key") as client:
            resource = await client.get_resource("res-123")
            print(resource.name)
        ```

    Raises:
        ValueError: If api_key is not provided
    """

    async def get_resource(self, resource_id: str) -> Resource:
        """
        Get a resource by ID.

        Args:
            resource_id: The resource identifier

        Returns:
            Resource object with id, name, and other fields

        Raises:
            ResourceNotFoundError: If resource doesn't exist
            AuthenticationError: If authentication fails
            SDKError: For other API errors

        Example:
            ```python
            resource = await client.get_resource("res-123")
            assert resource.id == "res-123"
            ```
        """

Generate with Sphinx:

pip install sphinx sphinx-rtd-theme
sphinx-apidoc -o docs/api src/
sphinx-build -b html docs/ docs/_build/html

.NET Documentation

Use XML documentation comments:

/// <summary>
/// Client for Infiquetra Service API.
/// </summary>
/// <example>
/// <code>
/// using var client = new ServiceClient("your-api-key");
/// var resource = await client.GetResourceAsync("res-123");
/// Console.WriteLine(resource.Name);
/// </code>
/// </example>
public class ServiceClient
{
    /// <summary>
    /// Gets a resource by ID.
    /// </summary>
    /// <param name="resourceId">The resource identifier</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The resource</returns>
    /// <exception cref="ResourceNotFoundException">Thrown when resource is not found</exception>
    /// <exception cref="AuthenticationException">Thrown when authentication fails</exception>
    public async Task<Resource> GetResourceAsync(
        string resourceId,
        CancellationToken cancellationToken = default)
    {
        // Implementation
    }
}

Generate with DocFX:

dotnet tool install -g docfx
docfx init
docfx build

TypeScript Documentation

Use JSDoc comments:

/**
 * Client for Infiquetra Service API.
 *
 * @example
 * ```typescript
 * const client = new VECUServiceClient({ apiKey: 'your-key' });
 * const resource = await client.getResource('res-123');
 * console.log(resource.name);
 * ```
 */
export class VECUServiceClient {
  /**
   * Gets a resource by ID.
   *
   * @param resourceId - The resource identifier
   * @returns The resource
   * @throws {ResourceNotFoundError} When resource is not found
   * @throws {AuthenticationError} When authentication fails
   *
   * @example
   * ```typescript
   * const resource = await client.getResource('res-123');
   * ```
   */
  async getResource(resourceId: string): Promise<Resource> {
    // Implementation
  }
}

Generate with TypeDoc:

npm install --save-dev typedoc
npx typedoc --out docs src/index.ts

Step 4: Create Usage Examples

Quickstart Example

# examples/quickstart.py
"""
Quickstart example for Infiquetra Service SDK.

This example demonstrates:
- Authentication
- Getting a resource
- Error handling
"""

import asyncio
from vecu_service_sdk import Client, SDKError


async def main():
    # Initialize client with API key
    async with Client(api_key="your-api-key") as client:
        try:
            # Get a resource
            resource = await client.get_resource("res-123")
            print(f"Resource: {resource.name}")

        except SDKError as e:
            print(f"Error: {e}")


if __name__ == "__main__":
    asyncio.run(main())

Advanced Examples

Create examples for:

• Pagination
• Error handling
• Retry logic
• Rate limiting
• Custom configuration
• Webhook handling
• Batch operations

Step 5: documentation portal Integration

Publish to documentation portal

# Generate documentation
python sdk_docs.py --project-path . --output-dir docs/

# Sync to documentation portal
rsync -avz docs/ documentation portal:/var/www/docs/sdk-name/

# Or use documentation portal CLI
documentation portal publish --project sdk-name --docs docs/

documentation portal Configuration

# .documentation portal.yml