SDK Documentation: Auto-Generated API Docs, Examples, and Getting Started Guides

Documentation Is the SDK

For most developers, documentation is the product. They evaluate your SDK by how quickly they can get a working example running, not by reading your source code. Poor documentation kills adoption regardless of how elegant the implementation is.

SDK documentation has three layers: getting started guides that show the first five minutes, API references generated from code that cover every method, and cookbook examples that solve real problems. Each layer serves a different moment in the developer journey.

Docstring Standards for Python

Every public class and method needs a docstring that follows a consistent format. Google-style docstrings work well because they are readable both in source code and when rendered by Sphinx:

flowchart LR
    INPUT(["User intent"])
    PARSE["Parse plus<br/>classify"]
    PLAN["Plan and tool<br/>selection"]
    AGENT["Agent loop<br/>LLM plus tools"]
    GUARD{"Guardrails<br/>and policy"}
    EXEC["Execute and<br/>verify result"]
    OBS[("Trace and metrics")]
    OUT(["Outcome plus<br/>next action"])
    INPUT --> PARSE --> PLAN --> AGENT --> GUARD
    GUARD -->|Pass| EXEC --> OUT
    GUARD -->|Fail| AGENT
    AGENT --> OBS
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style OBS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff

class AgentsResource:
    """Operations for managing AI agents.

    Use this resource to create, retrieve, update, and delete agents
    on the MyAgent platform. Access it through the client:

    Example:
        >>> client = AgentClient(api_key="sk-...")
        >>> agent = client.agents.create(name="Bot", model="gpt-4o")
        >>> print(agent.id)
        'agent_abc123'
    """

    def create(
        self,
        name: str,
        model: str = "gpt-4o",
        instructions: str = "",
        tool_ids: list[str] | None = None,
    ) -> Agent:
        """Create a new AI agent.

        Args:
            name: A human-readable name for the agent. Must be unique
                within your organization.
            model: The language model to use. Defaults to "gpt-4o".
                Supported: "gpt-4o", "gpt-4o-mini", "claude-3-opus".
            instructions: System instructions that define the agent's
                behavior. Supports Markdown formatting.
            tool_ids: Optional list of tool IDs to attach to the agent.

        Returns:
            The created Agent with a server-assigned ID.

        Raises:
            AuthenticationError: If the API key is invalid.
            APIError: If the server rejects the configuration.
            ValidationError: If parameters fail client-side validation.

        Example:
            >>> agent = client.agents.create(
            ...     name="Support Bot",
            ...     model="gpt-4o",
            ...     instructions="Answer customer questions politely.",
            ... )
        """

The Args, Returns, Raises, and Example sections are not optional. Every public method needs all four. This discipline ensures that auto-generated documentation is complete without manual editing.

Auto-Generating Python Docs with Sphinx

Sphinx with the autodoc and napoleon extensions generates a full API reference from your docstrings:

# docs/conf.py
project = "MyAgent Python SDK"
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
    "sphinx.ext.intersphinx",
    "sphinx_copybutton",
]

autodoc_member_order = "bysource"
napoleon_google_docstring = True
napoleon_include_init_with_doc = True
autodoc_typehints = "description"

Structure your RST files to mirror the SDK's resource hierarchy:

.. toctree::
   :maxdepth: 2

   getting-started
   api/client
   api/agents
   api/runs
   api/tools
   api/errors
   cookbook/index

Each API page uses automodule to pull documentation from the source:

Agents
======

.. autoclass:: myagent.resources.agents.AgentsResource
   :members:
   :undoc-members:
   :show-inheritance:

TypeScript Documentation with TypeDoc

For TypeScript SDKs, TypeDoc generates API references from JSDoc comments and TypeScript types:

/**
 * Operations for managing AI agents.
 *
 * @example
 * ~~~typescript
 * const agent = await client.agents.create({
 *   name: 'Support Bot',
 *   model: 'gpt-4o',
 * });
 * ~~~
 *
 * @group Resources
 */
export class AgentsResource {
  /**
   * Create a new AI agent.
   *
   * @param params - Agent configuration parameters.
   * @returns The created agent with a server-assigned ID.
   * @throws {@link AuthenticationError} If the API key is invalid.
   *
   * @example
   * ~~~typescript
   * const agent = await client.agents.create({
   *   name: 'Support Bot',
   *   model: 'gpt-4o',
   *   instructions: 'Be helpful and concise.',
   * });
   * console.log(agent.id);
   * ~~~
   */
  async create(params: CreateAgentParams): Promise<Agent> {
    // ...
  }
}

Configure TypeDoc in your project:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "plugin": ["typedoc-plugin-markdown"],
  "excludePrivate": true,
  "excludeInternal": true,
  "categorizeByGroup": true
}

Testing Code Examples

Documentation examples that do not compile or run are worse than no examples. Test them automatically:

# In Python, use doctest or pytest-examples
# pytest.ini
[tool.pytest.ini_options]
addopts = "--doctest-modules"

For standalone examples in a docs/examples/ directory:

# docs/examples/test_quickstart.py
"""This file doubles as documentation and a test."""

def test_quickstart():
    """Demonstrates basic SDK usage."""
    from myagent import AgentClient

    client = AgentClient(api_key="test-key")
    # Use VCR cassette to avoid live API calls
    agent = client.agents.create(name="Test", model="gpt-4o")
    assert agent.name == "Test"

The Getting Started Guide

The getting started guide is the single most important documentation page. It must take a developer from zero to a working example in under five minutes:

1. Install — one command, no prerequisites beyond Python/Node
2. Authenticate — set one environment variable
3. First request — five lines of code that produce visible output
4. Next steps — links to the three most common use cases

## Quick Start

Install the SDK:

pip install myagent

Set your API key:

export MYAGENT_API_KEY=sk-your-key

Run your first agent:

from myagent import AgentClient

client = AgentClient()
result = client.quick_run("What is 2 + 2?")
print(result.output)

Every line in the getting started guide must be copy-pasteable and produce the advertised result. Test this guide in CI.

FAQ

How do I keep documentation in sync with code changes?

Auto-generate API references from docstrings — this eliminates drift for the reference layer. For guides and cookbooks, include them in the CI pipeline as tested scripts. Any code example that cannot run in CI gets flagged as a broken test, forcing an update before merge.

Should I maintain separate documentation sites for each SDK version?

Yes. Use versioned documentation (for example, docs.myagent.ai/python/v0.3/) so that users on older SDK versions can find accurate references. Tools like ReadTheDocs and Docusaurus support version switching natively. Always link the latest version prominently and include a migration guide between major versions.

How detailed should error documentation be?

Document every exception class with its meaning, common causes, and recommended user action. For example, RateLimitError should explain what the rate limit is, how to check remaining quota, and how to configure the SDK's built-in retry to handle it automatically. Error messages are documentation too — make them actionable.

---

#Documentation #APIDocs #DeveloperTools #Sphinx #TypeDoc #AgenticAI #LearnAI #AIEngineering