Add auto-generated Python API reference documentation from software-agent-sdk

[xingyaoww]

Background

The OpenHands SDK provides a Python API for building AI agents, but currently lacks comprehensive API reference documentation on the docs site. Having clear, auto-generated Python API documentation is standard practice and would:

• Make it easier for users to discover available classes, methods, and parameters
• Encourage us to keep code comments and docstrings up to date
• Provide a single source of truth for the Python API

Current State

We currently have two automated workflows that sync content from the OpenHands/software-agent-sdk repository:

1. Code Block Sync (.github/workflows/sync-docs-code-blocks.yml) - Syncs example code snippets from the SDK repo into documentation pages
2. OpenAPI Sync (.github/workflows/sync-agent-sdk-openapi.yml) - Generates and syncs OpenAPI specifications from the SDK's agent server

These workflows demonstrate the pattern for automatically pulling content from the SDK repository and updating the docs.

Proposed Solution

Create a new GitHub Actions workflow similar to the existing sync workflows that:

1. Checks out the OpenHands/software-agent-sdk repository
2. Generates Python API documentation using a tool like:
   • Sphinx with autodoc
   • pdoc
   • mkdocstrings
   • Or another documentation generation tool
3. Converts the output to Mintlify-compatible format (MDX)
4. Commits and pushes the generated documentation to the docs repository
5. Runs on a schedule (e.g., daily) and on-demand via workflow_dispatch

Implementation Considerations

• Scope: Decide which modules/classes to include (e.g., public API only)
• Format: Ensure output is compatible with Mintlify's MDX format
• Navigation: Update docs.json to include the new API reference section
• Styling: Consider include/exclude patterns for classes/methods to avoid noise
• Location: Suggest placing generated docs under sdk/api/ or similar

Example Workflow Structure

Similar to sync-agent-sdk-openapi.yml:

name: Sync SDK API Reference

on:
  schedule:
    - cron: '0 2 * * *'
  workflow_dispatch:
    inputs:
      agent_sdk_ref:
        description: 'Agent SDK branch/tag/commit to generate from'
        required: false
        default: 'main'

jobs:
  sync-api-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout docs repo
      - name: Checkout agent-sdk
      - name: Generate API documentation
      - name: Convert to MDX format
      - name: Update docs.json navigation
      - name: Commit and push

Benefits

✅ Standard documentation practice for Python libraries
✅ Easier API discovery for users
✅ Automated - stays in sync with SDK changes
✅ Encourages better docstrings in the codebase
✅ Follows existing patterns in our docs infrastructure

Related

• SDK Documentation: https://docs.openhands.dev/sdk
• SDK Repository: https://github.com/OpenHands/software-agent-sdk

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary

I've successfully implemented auto-generated Python API reference documentation for the OpenHands SDK as requested in issue #65. Here's what was delivered:

✅ Implementation Complete

New Files Created:

1. .github/workflows/sync-api-reference.yml - GitHub Actions workflow that:

   • Runs daily at 2 AM UTC to keep docs in sync
   • Supports manual triggering via workflow_dispatch
   • Automatically checks out both repos, generates docs, and commits changes

2. .github/scripts/generate_api_docs.py - Custom Python documentation generator that:

   • Uses AST parsing (no external dependencies required)
   • Extracts docstrings, classes, methods, and function signatures
   • Generates Mintlify-compatible MDX files with proper frontmatter
   • Filters out private members (except __init__)
   • Links to GitHub source code for each module

3. sdk/api/ directory - 12 auto-generated documentation files:

   • index.mdx - Overview page with module list
   • 11 module pages: agent, conversation, llm, tool, workspace, mcp, event, context, security, io, git

4. docs.json updates - Added "API Reference" section to SDK tab navigation

🎯 Key Features

• Zero dependencies: Uses Python standard library only (ast, json, pathlib)
• Automated sync: Keeps documentation current with SDK changes
• Clean output: Professional MDX format with class hierarchies, method signatures, and docstrings
• Source links: Every module links to its GitHub source location
• Maintainable: Simple, readable code that's easy to extend

📋 All Requirements Met

✅ GitHub Actions workflow with schedule and workflow_dispatch
✅ Checks out software-agent-sdk repository
✅ Generates Python API documentation
✅ Outputs Mintlify-compatible MDX format
✅ Auto-commits and pushes changes
✅ Updates docs.json navigation
✅ Filters to public API only
✅ Documentation placed in sdk/api/

🔗 Pull Request

PR #69: #69

The PR has been created as a draft and includes all changes with a detailed description. The implementation is ready for review and testing.

_{View full conversation}