Add auto-generated Python API reference documentation

[xingyaoww]

Fixes #65

Summary

This PR implements auto-generated Python API reference documentation from the software-agent-sdk repository as requested in issue #65.

Changes

New GitHub Actions Workflow

• .github/workflows/sync-api-reference.yml: Automated workflow that runs daily at 2 AM UTC and on workflow_dispatch
• Checks out both docs and agent-sdk repositories
• Generates API documentation using custom Python script
• Commits and pushes changes automatically

Documentation Generation Script

• .github/scripts/generate_api_docs.py: Python script that uses AST parsing to extract documentation
• Parses Python source files without requiring SDK dependencies or environment setup
• Extracts module docstrings, class definitions, methods, and function signatures
• Generates Mintlify-compatible MDX files with proper frontmatter
• Creates links to GitHub source code for each module
• Updates docs.json navigation automatically

Generated Documentation

• sdk/api/: New directory containing auto-generated API reference
  • index.mdx - Overview page with module list and descriptions
  • 11 module pages: agent.mdx, conversation.mdx, llm.mdx, tool.mdx, workspace.mdx, mcp.mdx, event.mdx, context.mdx, security.mdx, io.mdx, git.mdx
• Each module page includes:
  • Classes with docstrings
  • Methods with signatures and docstrings
  • Functions with signatures and docstrings
  • Links to GitHub source code

Navigation Updates

• docs.json: Added "API Reference" section to SDK tab navigation
• Placed after Architecture section for logical flow

Implementation Highlights

• AST-based parsing: Uses Python's ast module for robust source code parsing without requiring SDK installation
• No dependencies: Script only uses Python standard library (ast, json, pathlib)
• Automatic syncing: Workflow ensures docs stay up-to-date with SDK changes
• Mintlify-compatible: Generated MDX follows Mintlify format with proper frontmatter
• Clean output: Filters out private methods/classes (except __init__)

Testing

• Tested script locally with agent-sdk repository
• Verified MDX files are properly formatted
• Confirmed docs.json navigation updates correctly
• Checked GitHub source links point to correct locations

Checklist

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Next Steps

After this PR is merged:

1. The workflow will run automatically daily to keep docs in sync
2. Manual runs can be triggered via workflow_dispatch if immediate updates are needed
3. Future enhancements could include:
   • Enhanced docstring parsing (Google/NumPy style)
   • Cross-referencing between modules
   • Search functionality optimization

@xingyaoww can click here to continue refining the PR

[xingyaoww]

Update: Flattened API Reference

I've updated this PR with a new approach based on feedback:

Changes

✅ Single-file output: Combined all SDK modules into one sdk/api/index.mdx file (7214 lines)
✅ Uses established library: Replaced custom AST parser with pydoc-markdown
✅ No import required: pydoc-markdown parses source without importing, avoiding dependency issues
✅ Cleaner navigation: docs.json now references only one file instead of 12 separate files

Technical Details

• Generator: .github/scripts/generate_api_docs.py (rewritten)
• Library: Uses pydoc-markdown -I <path> -p openhands.sdk --render-toc
• Output: Single MDX file with table of contents and all API documentation
• Workflow: .github/workflows/sync-api-reference.yml installs pydoc-markdown via pip

Files Changed

• ✏️ Updated generator script to use pydoc-markdown
• ✏️ Updated workflow to install pydoc-markdown dependency
• ✏️ Updated docs.json to reference single API file
• ➕ Generated sdk/api/index.mdx (comprehensive API reference)
• 🗑️ Removed 11 separate module MDX files (agent, conversation, llm, tool, etc.)

Benefits

1. Simpler maintenance: One file to manage instead of 12
2. Standard tooling: Uses widely-adopted pydoc-markdown instead of custom solution
3. Better UX: Single searchable page for all API documentation
4. Reliable: No import issues since pydoc-markdown parses AST directly

Ready for review! 🚀

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Check Broken Links
  • .github/workflows/sync-api-reference.yml

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #69 at branch `openhands/add-api-reference-docs`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[xingyaoww]

#72 is better