chore: use Sphinx for api doc generation

.github/workflows/api-doc.yml

@@ -0,0 +1,96 @@
+name: api-doc
+
+on:
+  push:
+    tags:
+      - 'gen-v*'
+      - 'base-v*'
+      - 'core-v*'
+  workflow_dispatch: ~
+
+jobs:
+  doc:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ secrets.SAP_AI_SDK_BOT_CLIENT_ID }}
+          private-key: ${{ secrets.SAP_AI_SDK_BOT_PRIVATE_KEY }}
+          repositories: |
+            ai-sdk-python
+            ai-sdk
+          permission-contents: write
+          permission-pull-requests: write
+
+      - name: Setup
+        uses: SAP/ai-sdk-python/.github/actions/setup@main
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          ref: ${{ github.ref }}
+      - name: Generate docs
+        run: uv run make docs
+
+      - name: Checkout sap/ai-sdk
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          repository: SAP/ai-sdk
+          token: ${{ steps.app-token.outputs.token }}
+          path: ai-sdk
+          persist-credentials: false
+
+      - name: Configure git
+        env:
+          BOT_EMAIL: ${{ vars.SAP_AI_SDK_BOT_EMAIL }}
+          BOT_NAME: ${{ vars.SAP_AI_SDK_BOT_NAME }}
+        run: |
+          git -C ai-sdk config user.email "$BOT_EMAIL"
+          git -C ai-sdk config user.name "$BOT_NAME"
+
+      - name: Update api docs
+        id: update-docs
+        env:
+          REF: ${{ github.ref_name }}
+        run: |
+          BRANCH="api-docs-python-$REF"
+          echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
+          cd ai-sdk
+          git checkout -b "$BRANCH"
+          rm -rf static/api-python
+          cp -r ../api-docs/ static/api-python
+          git add static/api-python
+          if git diff --cached --quiet; then
+            echo "No documentation changes to commit"
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            git commit -m "chore: update Python API docs ($REF)"
+            git push --force origin "$BRANCH"
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create pull request
+        if: steps.update-docs.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REF: ${{ github.ref_name }}
+          BRANCH: ${{ steps.update-docs.outputs.branch }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = "workflow_dispatch" ]; then
+            REF_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/tree/$REF"
+          else
+            REF_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/tag/$REF"
+          fi
+          if gh pr list --repo SAP/ai-sdk --head "$BRANCH" --json number --jq '.[0].number' | grep -q .; then
+            echo "Pull request already exists for branch $BRANCH"
+          else
+            gh pr create \
+              --repo SAP/ai-sdk \
+              --base main \
+              --head "$BRANCH" \
+              --title "chore: update Python API docs ($REF)" \
+              --body "Automated update of Python API docs from [$REF]($REF_URL) in SAP/ai-sdk-python."
+          fi

.gitignore

@@ -68,8 +68,12 @@ instance/
 # Scrapy stuff:
 .scrapy
 
+# Generated API docs
+api-docs/
+
 # Sphinx documentation
 **/docs/_build/
+docs/sphinx/_autogen/
 **/docs/source/_reference
 **/docs/source/_api_doc
 

Makefile

@@ -1,6 +1,25 @@
+.PHONY: install docs lint license-check test test-integration test-pkg test-pkg-integration
+
 install:
 	uv sync --all-packages --all-extras
 
+docs:
+	uv run sphinx-apidoc -e -M -f -T \
+		-o docs/sphinx/_autogen/base \
+		packages/base/ai_api_client_sdk \
+		packages/base/ai_api_client_sdk/helpers
+	uv run sphinx-apidoc -e -M -f -T \
+		-o docs/sphinx/_autogen/core \
+		packages/core/ai_core_sdk \
+		packages/core/ai_core_sdk/helpers \
+		packages/core/ai_core_sdk/cli.py
+	uv run sphinx-apidoc -e -M -f -T \
+		-o docs/sphinx/_autogen/gen \
+		packages/gen/gen_ai_hub \
+		packages/gen/gen_ai_hub/evaluations/_internal \
+		packages/gen/gen_ai_hub/evaluations/helpers
+	uv run sphinx-build -b html docs/sphinx api-docs/
+
 lint:
 	uv run pylint ai_api_client_sdk ai_core_sdk gen_ai_hub --errors-only --output-format=colorized
 

docs/sphinx/conf.py

@@ -0,0 +1,15 @@
+project = "SAP AI SDK Python"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+html_theme = "furo"
+exclude_patterns = ["_autogen/*/modules.rst"]
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "private-members": False,
+    "show-inheritance": True,
+    "special-members": "__init__",
+}
+autodoc_member_order = "bysource"

docs/sphinx/index.rst

@@ -0,0 +1,17 @@
+SAP AI SDK Python
+=================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Packages
+
+   _autogen/base/ai_api_client_sdk
+   _autogen/core/ai_core_sdk
+   _autogen/gen/gen_ai_hub
+
+Indices
+-------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`