From sdk-lifecycle
Generate comprehensive SDK documentation including API references, usage guides, and documentation portal integration
npx claudepluginhub infiquetra/infiquetra-claude-plugins --plugin sdk-lifecycleThis skill uses the workspace's default tool permissions.
You are helping the user generate comprehensive documentation for their SDK.
Provides Ktor server patterns for routing DSL, plugins (auth, CORS, serialization), Koin DI, WebSockets, services, and testApplication testing.
Conducts multi-source web research with firecrawl and exa MCPs: searches, scrapes pages, synthesizes cited reports. For deep dives, competitive analysis, tech evaluations, or due diligence.
Provides demand forecasting, safety stock optimization, replenishment planning, and promotional lift estimation for multi-location retailers managing 300-800 SKUs.
You are helping the user generate comprehensive documentation for their SDK.
The sdk-documentation skill provides:
Before generating documentation:
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:
Fill in the generated templates:
# 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
## 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)
\`\`\`
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
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
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
# 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())
Create examples for:
# 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.yml
name: service-sdk
version: 1.0.0
language: python
docs:
source: docs/
target: /service-sdk
index: README.md
api_reference: api/index.html
navigation:
- title: Quick Start
path: quickstart.md
- title: API Reference
path: api/
- title: Examples
path: examples/
Ensure all code examples work:
# tests/test_examples.py
"""Test that documentation examples work."""
import subprocess
import pytest
from pathlib import Path
def test_quickstart_example():
"""Test quickstart example runs successfully."""
result = subprocess.run(
["python", "examples/quickstart.py"],
capture_output=True,
text=True,
timeout=30,
)
assert result.returncode == 0
assert "Resource:" in result.stdout
# Good: Show working code
async with Client(api_key="key") as client:
resource = await client.get_resource("res-123")
# Bad: Explain without code
"First create a client, then call get_resource..."
Raises:
ResourceNotFoundError: When resource_id doesn't exist
AuthenticationError: When API key is invalid
RateLimitError: When rate limit exceeded (429 response)
name: Documentation
on:
push:
branches: [main]
release:
types: [published]
jobs:
build-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate documentation
run: |
python sdk_docs.py --project-path . --output-dir docs/
- name: Validate examples
run: pytest tests/test_examples.py
- name: Publish to documentation portal
run: |
documentation portal publish --project ${{ github.repository }} --docs docs/
After generating documentation:
For detailed documentation patterns, see:
references/api-reference-template.md - API documentation structurereferences/usage-guide-template.md - User guide structurereferences/documentation portal-integration.md - Publishing workflow