feat: Add automated API documentation generation pipeline

.github/workflows/sync-docs-code-blocks.yml

@@ -38,14 +38,30 @@ jobs:
         with:
           python-version: '3.11'
 
+      - name: Install dependencies for API docs
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx-markdown-builder myst-parser
+
       - name: Sync code blocks
-        id: detect_changes
         env:
           AGENT_SDK_PATH: ${{ github.workspace }}/agent-sdk
         shell: bash
         run: |
           set -euo pipefail
           python .github/scripts/sync_code_blocks.py
+
+      - name: Generate API documentation
+        shell: bash
+        run: |
+          set -euo pipefail
+          python scripts/generate-api-docs.py
+
+      - name: Check for changes
+        id: detect_changes
+        shell: bash
+        run: |
+          set -euo pipefail
           if [[ -n "$(git status --porcelain)" ]]; then
             echo "changes=true" >> "$GITHUB_OUTPUT"
           else
@@ -57,26 +73,25 @@ jobs:
         uses: peter-evans/create-pull-request@v7
         with:
           commit-message: |
-            docs: sync code blocks from agent-sdk examples
-            
+            docs: sync code blocks and generate API reference
+
             Synced from agent-sdk ref: ${{ github.event.inputs.agent_sdk_ref || 'main' }}
-          branch: sync-docs-code-blocks
+          branch: sync-docs-and-api
           branch-suffix: timestamp
           delete-branch: true
-          title: "docs: sync code blocks from agent-sdk examples"
+          title: "docs: sync code blocks and generate API reference"
           body: |
             ## Summary of changes
 
-            This PR automatically syncs code blocks in documentation with their corresponding source files from the agent-sdk repository.
+            This PR automatically syncs code blocks in documentation with their corresponding source files from the agent-sdk repository, and generates API reference documentation.
 
             **Agent SDK Reference**: `${{ github.event.inputs.agent_sdk_ref || 'main' }}`
 
             ### Changes Made
             - Updated code blocks in MDX files to match the current state of example files in agent-sdk
+            - Generated API reference markdown files
             - This is an automated sync performed by the `sync-docs-code-blocks` workflow
 
             ### Checklist
             - [x] I have read and reviewed the documentation changes to the best of my ability.
             - [x] If the change is significant, I have run the documentation site locally and confirmed it renders as expected.
-
-            **Note**: This is an automated pull request. Please review the changes to ensure they are correct before merging.

.gitignore

@@ -1,6 +1,34 @@
 # Local checkout of agent-sdk for docs workflows and local testing
 agent-sdk/
 
+# Sphinx build artifacts
+scripts/sphinx/build/
+scripts/sphinx/source/*.rst
+!scripts/sphinx/source/index.rst
+!scripts/sphinx/source/conf.py
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+
+# Virtual environments
+venv/
+env/
+.env
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
 # OS junk
 .DS_Store
 Thumbs.db
+
+# Keep generated API reference docs (these should be committed)
+# api-reference/ - This directory should be committed

docs.json

@@ -140,7 +140,9 @@
           },
           {
             "group": "Tips and Tricks",
-            "pages": ["openhands/usage/tips/prompting-best-practices"]
+            "pages": [
+              "openhands/usage/tips/prompting-best-practices"
+            ]
           },
           {
             "group": "Troubleshooting & Feedback",
@@ -258,6 +260,19 @@
                 ]
               }
             ]
+          },
+          {
+            "group": "API Reference",
+            "pages": [
+              "sdk/api-reference/openhands.sdk.agent",
+              "sdk/api-reference/openhands.sdk.conversation",
+              "sdk/api-reference/openhands.sdk.event",
+              "sdk/api-reference/openhands.sdk.llm",
+              "sdk/api-reference/openhands.sdk.security",
+              "sdk/api-reference/openhands.sdk.tool",
+              "sdk/api-reference/openhands.sdk.utils",
+              "sdk/api-reference/openhands.sdk.workspace"
+            ]
           }
         ]
       },
@@ -267,7 +282,9 @@
       },
       {
         "tab": "Success Stories",
-        "pages": ["success-stories/index"]
+        "pages": [
+          "success-stories/index"
+        ]
       }
     ],
     "global": {
@@ -308,7 +325,7 @@
     }
   },
   "banner": {
-    "content": "📢 **GitHub Org Rename:** All-Hands-AI to OpenHands on Monday Oct 20th at 18:00 UTC. [Migration details →](https://github.com/OpenHands/OpenHands/issues/11376)",
+    "content": "\ud83d\udce2 **GitHub Org Rename:** All-Hands-AI to OpenHands on Monday Oct 20th at 18:00 UTC. [Migration details \u2192](https://github.com/OpenHands/OpenHands/issues/11376)",
     "dismissible": true
   },
   "head": [
@@ -320,11 +337,22 @@
     }
   ],
   "contextual": {
-    "options": ["copy", "view", "chatgpt", "claude"]
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude"
+    ]
   },
   "redirects": [
-    { "source": "/modules/:slug*", "destination": "/:slug*" },
-    { "source": "/usage/:slug*", "destination": "/openhands/usage/:slug*" },
+    {
+      "source": "/modules/:slug*",
+      "destination": "/:slug*"
+    },
+    {
+      "source": "/usage/:slug*",
+      "destination": "/openhands/usage/:slug*"
+    },
     {
       "source": "/openhands/usage/configuration-options",
       "destination": "/openhands/usage/advanced/configuration-options"
@@ -414,4 +442,4 @@
       "destination": "/openhands/usage/troubleshooting/feedback"
     }
   ]
-}
+}