Skip to content

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

Closed as not planned
Closed as not planned
Add auto-generated Python API reference documentation from software-agent-sdk#65
Assignees
VascoSch92
Labels
documentationImprovements or additions to documentationenhancementNew feature or requestopenhands

Description

@xingyaoww
xingyaoww
opened on Nov 3, 2025

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:
  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

Activity

  1. xingyaoww
    added
    documentationImprovements or additions to documentation
    enhancementNew feature or request
    openhands
    on Nov 3, 2025

  2. openhands-ai commented on Nov 3, 2025

    @openhands-ai
    openhands-aibot
    on Nov 3, 2025 – with OpenHands AI

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

  3. xingyaoww
    added a commit that references this issue on Nov 3, 2025

    Add auto-generated Python API reference documentation

    61463a0

  4. openhands-ai commented on Nov 3, 2025

    @openhands-ai
    openhands-aibot
    on Nov 3, 2025 – with 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

  5. enyst
    added a commit that references this issue on Nov 8, 2025

    Port over microagent changes in OpenHands/OpenHands#10528 (#65)

    936df5c

  6. VascoSch92 commented on Jan 27, 2026

    @VascoSch92
    VascoSch92
    on Jan 27, 2026
    Member

    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 ;-)

  7. xingyaoww commented on Jan 30, 2026

    @xingyaoww
    xingyaoww
    on Jan 30, 2026
    ContributorAuthor

    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!

  8. VascoSch92
    self-assigned this
    on Feb 3, 2026

  9. VascoSch92 commented on Feb 3, 2026

    @VascoSch92
    VascoSch92
    on Feb 3, 2026
    Member

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

  10. linear
    closed this as not plannedon Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or requestopenhands

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions