This directory contains the automated pipeline for generating API reference documentation from the OpenHands software-agent-sdk repository.

The pipeline uses Sphinx with the sphinx-markdown-builder extension to generate clean, parser-friendly Markdown files from Python docstrings. The output is specifically designed to avoid JavaScript parsing errors in Mintlify by using simple headers and clean formatting.

• Simple headers: Just class names (### ClassName) and method names (#### method_name)
• No complex signatures: Parameters documented as readable text, not in headers
• Parser-friendly: Eliminates asterisks, emphasis, and patterns that cause acorn parsing errors
• Organized structure: 9 module-level pages instead of 100+ individual files

scripts/
├── README.md                    # This file
├── generate-api-docs.py         # Main generation script
├── mint-config-snippet.json     # Generated Mintlify config snippet
└── sphinx/
    └── source/
        ├── conf.py              # Sphinx configuration
        └── index.rst            # Main documentation index

We recommend using uv to run the generator with an ephemeral environment (no global installs required):

uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py

(Alternatively, you can install the same dependencies into your own venv with uv pip install ... or pip install ....)

• Python 3.8+

Generate API documentation with default settings:

cd docs
uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py

# Clean previous build and regenerate everything
uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py --clean

# Enable verbose output for debugging
uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py --verbose

# Combine options
uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py --clean --verbose

• --clean: Remove all previous build artifacts and generated documentation before starting
• --verbose, -v: Enable detailed logging output for debugging

The generation pipeline follows these steps:

1. Dependency Check: Verifies that required Python packages are installed
2. Repository Management: Clones or updates the software-agent-sdk repository
3. Sphinx Setup: Creates necessary Sphinx directories and configuration
4. RST Generation: Uses sphinx-apidoc to generate RST files from Python source
5. Markdown Build: Runs Sphinx with the markdown builder to generate clean Markdown
6. Content Organization: Processes and organizes the generated Markdown files
7. Mintlify Integration: Creates configuration snippets for easy integration
8. Cleanup: Removes build artifacts while preserving generated documentation

The script generates the following:

• sdk/api-reference/: Directory containing all generated API documentation
  • openhands.sdk.mdx: Main SDK module documentation
  • openhands.sdk.agent.mdx: Agent system documentation
  • openhands.sdk.conversation.mdx: Conversation management documentation
  • openhands.sdk.event.mdx: Event system documentation
  • openhands.sdk.llm.mdx: LLM integration documentation
  • openhands.sdk.security.mdx: Security features documentation
  • openhands.sdk.tool.mdx: Tool system documentation
  • openhands.sdk.utils.mdx: Utilities documentation
  • openhands.sdk.workspace.mdx: Workspace management documentation

• scripts/mint-config-snippet.json: Ready-to-use configuration snippet for docs.json

The generated mint-config-snippet.json contains the navigation structure for the API reference:

{
  "group": "API Reference",
  "pages": [
    "sdk/api-reference/index",
    "sdk/api-reference/sdk.agent",
    "sdk/api-reference/sdk.conversation",
    ...
  ]
}

To integrate the API reference into your docs.json:

1. Run the generation script
2. Copy the contents of scripts/mint-config-snippet.json
3. Add it to the appropriate section in your docs.json navigation

Example integration in docs.json:

{
  "navigation": {
    "tabs": [
      {
        "tab": "SDK",
        "pages": [
          "sdk/index",
          "sdk/getting-started",
          {
            "group": "Guides",
            "pages": ["..."]
          },
          {
            "group": "API Reference",
            "pages": [
              "api-reference/index",
              "api-reference/openhands.agent",
              "api-reference/openhands.conversation"
            ]
          }
        ]
      }
    ]
  }
}

Modify scripts/sphinx/source/conf.py to customize:

• Extensions: Add or remove Sphinx extensions
• Autodoc Options: Control what gets documented
• Napoleon Settings: Configure docstring parsing
• Markdown Output: Adjust markdown generation settings

The script includes content processing functions that can be customized:

• clean_markdown_file(): Modify how individual files are processed
• create_api_index(): Customize the main index page
• organize_output_docs(): Change how files are organized

To document specific modules only, modify the generate_rst_files() method in the script to include/exclude specific paths.

1. Missing Dependencies

   Error: Missing required packages: sphinx, sphinx_markdown_builder, myst_parser
   

   Solution: Run the script via uv run --with ... (recommended), or install the required packages into your environment.

2. SDK Repository Not Found

   Error: openhands-sdk directory not found
   

   Solution: Ensure the SDK repository is properly cloned and contains the expected structure

3. Permission Errors

   Error: Permission denied when writing files
   

   Solution: Check file permissions and ensure the script has write access to the docs directory

Use the --verbose flag to get detailed logging:

uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py --verbose

This will show:

• Command execution details
• File processing steps
• Sphinx build output
• Error stack traces

If the script fails partway through, you can manually clean up:

# Remove build artifacts
rm -rf scripts/sphinx/build/
rm -rf scripts/sphinx/source/openhands*.rst

# Remove generated docs (if needed)
rm -rf api-reference/

# Remove cloned repository (if needed)
rm -rf agent-sdk/

The repository includes an automated workflow (.github/workflows/sync-docs-and-api.yml) that:

• Runs daily at 2 AM UTC to keep documentation current
• Can be triggered manually with custom options
• Syncs both code blocks and API documentation from the agent-sdk repository

You can manually trigger the workflow with these options:

• agent_sdk_ref: Specify which branch/tag/commit to sync from (default: main)
• sync_code_blocks: Enable/disable code block synchronization (default: true)
• generate_api_docs: Enable/disable API documentation generation (default: true)

• Automatic dependency installation: Installs Sphinx and required packages
• Conditional execution: Skip code sync or API generation as needed
• Smart commit messages: Describes exactly what was updated
• Error handling: Fails gracefully with detailed error messages

For custom CI/CD setups, the script is designed to be idempotent and safe:

# Example GitHub Actions step
- uses: astral-sh/setup-uv@v7
- name: Generate API Documentation
  run: |
    cd docs
    uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
      python scripts/generate-api-docs.py --clean

If you prefer custom scheduling, you can set up your own workflow:

# Example custom workflow
name: Update API Docs
on:
  schedule:
    - cron: '0 6 * * 1'  # Weekly on Monday at 6 AM
  workflow_dispatch:

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - uses: astral-sh/setup-uv@v7
      - name: Generate documentation
        run: |
          cd docs
          uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
            python scripts/generate-api-docs.py --clean
      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add sdk/api-reference/
          git diff --staged --quiet || git commit -m "Update API documentation"
          git push

When modifying the generation pipeline:

1. Test changes locally with --verbose flag
2. Verify generated Markdown renders correctly in Mintlify
3. Check that all module documentation is complete
4. Update this README if adding new features or changing behavior

For issues with the documentation generation pipeline:

1. Check the troubleshooting section above
2. Run with --verbose to get detailed error information
3. Open an issue in the OpenHands/docs repository with the full error output