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}

[VascoSch92]

I’ve been reading the documentation and the existing tools for automated document generation. I noticed there is already a solution in place, but I have a question regarding its current status: Is this solution functional?

Asking that because I found here the following description for the method verify()

This PR’s goal is to not reconcile configuration between persisted and runtime Agent instances. Instead, we verify compatibility requirements and then continue with the runtime-provided Agent.

This text appears to be a leftover PR description rather than actual documentation, and it doesn't match the docstring found in the software-agent-sdk.

If you need help, I’d be happy to take a look at it ;-)

[xingyaoww]

Hey @VascoSch92 - yes, i think this solution is somewhat functional, but could be a little buggy based on your observation, so feel free to take a look to double check if you have time!

[VascoSch92]

@xingyaoww FYI: I assigned myself so I don't forget to look into that