From 827e7e75fdea286bbe47a691f918f99af3706c5b Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Mon, 8 Jun 2026 17:41:51 -0500
Subject: [PATCH 01/11] feat(docs): wire splunk-ao SDK reference doc
 auto-generation (HYBIM-725)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update all source paths and namespace references from galileo to splunk_ao
as part of the Splunk AO rebrand. Blocked on HYBIM-717 (src/galileo →
src/splunk_ao directory rename) before these changes can be validated.

Changes:
- pydoc-markdown.yml: search_path ./src/galileo → ./src/splunk_ao
- pydoc-markdown-handlers.yml: search_path updated for handlers submodule
- scripts/create_docs.py: SOURCE constant updated to ./src/splunk_ao
- scripts/auto-generate-api-client.sh: OUTPUT_PATH → ../src/splunk_ao/resources
- openapi-client-config.yaml: add package_name: splunk_ao

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 openapi-client-config.yaml          | 1 +
 pydoc-markdown-handlers.yml         | 2 +-
 pydoc-markdown.yml                  | 2 +-
 scripts/auto-generate-api-client.sh | 2 +-
 scripts/create_docs.py              | 2 +-
 5 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/openapi-client-config.yaml b/openapi-client-config.yaml
index 3b1e96e8..b877f596 100644
--- a/openapi-client-config.yaml
+++ b/openapi-client-config.yaml
@@ -1,3 +1,4 @@
+package_name: splunk_ao
 post_hooks:
   - "ruff check . --fix --select F,I"
   - "ruff format ."
diff --git a/pydoc-markdown-handlers.yml b/pydoc-markdown-handlers.yml
index e7ccf761..c666cc51 100644
--- a/pydoc-markdown-handlers.yml
+++ b/pydoc-markdown-handlers.yml
@@ -1,7 +1,7 @@
 # Special PyDoc markdown configuration for the Galileo handlers module as this isn't created by default for some reason
 loaders:
   - type: python
-    search_path: [./src/galileo/handlers]
+    search_path: [./src/splunk_ao/handlers]
     ignore_when_discovered: ["__pycache__", "constants", "resources", "schema"]
 
 processors:
diff --git a/pydoc-markdown.yml b/pydoc-markdown.yml
index fe6423f3..ad704bed 100644
--- a/pydoc-markdown.yml
+++ b/pydoc-markdown.yml
@@ -1,6 +1,6 @@
 loaders:
   - type: python
-    search_path: [./src/galileo]
+    search_path: [./src/splunk_ao]
     ignore_when_discovered: ["__pycache__", "constants", "resources", "schema"]
 
 processors:
diff --git a/scripts/auto-generate-api-client.sh b/scripts/auto-generate-api-client.sh
index aa1ed8da..e62a649d 100755
--- a/scripts/auto-generate-api-client.sh
+++ b/scripts/auto-generate-api-client.sh
@@ -9,7 +9,7 @@ set -euo pipefail
 # Define the paths to the OpenAPI spec and config file
 OPENAPI_SPEC_PATH="../openapi.yaml"
 CONFIG_PATH="../openapi-client-config.yaml"
-OUTPUT_PATH="../src/galileo/resources"
+OUTPUT_PATH="../src/splunk_ao/resources"
 
 HOME_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
diff --git a/scripts/create_docs.py b/scripts/create_docs.py
index bd397cf7..1b90f52e 100644
--- a/scripts/create_docs.py
+++ b/scripts/create_docs.py
@@ -780,7 +780,7 @@ def write_module(fd: FileDoc, parts: list[str]) -> None:
 
 
 if __name__ == "__main__":
-    SOURCE = "./src/galileo"
+    SOURCE = "./src/splunk_ao"
     ignore = ["__pycache__", "constants", "resources", "schema", "__future__"]
 
     details = parse_source(SOURCE, to_ignore=ignore)

From 13ef6fac2411a20572234b0c86438e67208938f2 Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Tue, 16 Jun 2026 11:39:26 -0500
Subject: [PATCH 02/11] fix: remove invalid package_name key; update stale
 handlers comment (HYBIM-725)

---
 openapi-client-config.yaml  | 1 -
 pydoc-markdown-handlers.yml | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/openapi-client-config.yaml b/openapi-client-config.yaml
index b877f596..3b1e96e8 100644
--- a/openapi-client-config.yaml
+++ b/openapi-client-config.yaml
@@ -1,4 +1,3 @@
-package_name: splunk_ao
 post_hooks:
   - "ruff check . --fix --select F,I"
   - "ruff format ."
diff --git a/pydoc-markdown-handlers.yml b/pydoc-markdown-handlers.yml
index c666cc51..79e2fde9 100644
--- a/pydoc-markdown-handlers.yml
+++ b/pydoc-markdown-handlers.yml
@@ -1,4 +1,4 @@
-# Special PyDoc markdown configuration for the Galileo handlers module as this isn't created by default for some reason
+# Special PyDoc markdown configuration for the Splunk AO handlers module as this isn't created by default for some reason
 loaders:
   - type: python
     search_path: [./src/splunk_ao/handlers]

From 69d4a97c8530874b98a407a9cc3a7b54b6544e55 Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Tue, 16 Jun 2026 16:17:40 -0500
Subject: [PATCH 03/11] feat(ci): add publish-docs and regenerate-api-client
 workflows; fix regen script (HYBIM-725)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add .github/workflows/publish-docs.yaml: triggers on release or workflow_dispatch;
  runs create_docs.py, verifies output, and opens a PR against splunk/agent-observability-docs.
  On pull_request, only build+verify steps run (cross-repo steps skipped until
  PAT_AO_DOC_AUTOMATION is provisioned with write access to agent-observability-docs).
- Add .github/workflows/regenerate-api-client.yaml: daily cron + manual dispatch;
  regenerates API client from OpenAPI spec and opens a PR.
- Hardcode docs repo as splunk/agent-observability-docs (confirmed destination).
- Keep OUTPUT_PATH at src/galileo/resources — resources not yet migrated to splunk_ao.
- Add CI_ENV: dev (present in upstream, was missing from initial port).
- Use PAT_CLATOOL for PR testing; rename final token secret to PAT_AO_DOC_AUTOMATION.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/publish-docs.yaml          | 98 ++++++++++++++++++++
 .github/workflows/regenerate-api-client.yaml | 83 +++++++++++++++++
 scripts/auto-generate-api-client.sh          |  4 +-
 3 files changed, 183 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/publish-docs.yaml
 create mode 100644 .github/workflows/regenerate-api-client.yaml

diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
new file mode 100644
index 00000000..1092377f
--- /dev/null
+++ b/.github/workflows/publish-docs.yaml
@@ -0,0 +1,98 @@
+# Publishes SDK docs to the Splunk AO docs repo.
+# TODO(HYBIM-725): Replace PAT_CLATOOL with a dedicated PAT_AO_DOC_AUTOMATION
+# (bot account with write access to splunk/agent-observability-docs) before production use.
+name: Publish Docs
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize]
+  workflow_run:
+    workflows: ["Package Release"]
+    types:
+      - completed
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          path: ./splunk-ao-python
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install Docstring Parser
+        run: pip install docstring-parser>=0.17.0
+
+      - name: Build Docs
+        working-directory: ./splunk-ao-python
+        run: python ./scripts/create_docs.py
+
+      - name: Verify Docs Output
+        working-directory: ./splunk-ao-python
+        run: |
+          count=$(find .generated_docs/reference -name "*.mdx" | wc -l)
+          echo "Generated $count .mdx files"
+          if [ "$count" -lt 1 ]; then
+            echo "ERROR: No .mdx files generated"
+            exit 1
+          fi
+
+      - name: Check out Docs repo
+        if: github.event_name != 'pull_request'
+        uses: actions/checkout@v5
+        with:
+          repository: splunk/agent-observability-docs
+          path: ./splunk-ao-docs
+          token: ${{ secrets.PAT_CLATOOL }}
+
+      - name: Create a branch
+        if: github.event_name != 'pull_request'
+        working-directory: ./splunk-ao-docs
+        run: git checkout -b feat/update-docs-${GITHUB_REF_NAME}-${{ github.run_id }}
+
+      - name: Update SDK docs
+        if: github.event_name != 'pull_request'
+        run: |
+          rm -rf ./splunk-ao-docs/sdk-api/python/reference
+          cp -r ./splunk-ao-python/.generated_docs/reference ./splunk-ao-docs/sdk-api/python/
+
+      - name: Commit changes
+        if: github.event_name != 'pull_request'
+        working-directory: ./splunk-ao-docs
+        run: |
+          # TODO(HYBIM-725): replace with Splunk bot email and name
+          git config --global user.email "splunk-ao-automation@splunk.com"
+          git config --global user.name "splunk-ao-automation"
+          git add .
+          git commit -m "Updating docs from ${GITHUB_REF_NAME}-${{ github.run_id }}"
+          git push -u origin feat/update-docs-${GITHUB_REF_NAME}-${{ github.run_id }}
+
+      - name: Create PR
+        if: github.event_name != 'pull_request'
+        working-directory: ./splunk-ao-docs
+        env:
+          GH_TOKEN: ${{ secrets.PAT_CLATOOL }}
+          PR_BODY: |
+            This PR contains the latest updates to the Splunk AO Python SDK documentation.
+
+            The SDK doc generation will not change docs.json for new or removed files, so you
+            will need to manually commit a change to this PR for any file changes.
+
+            When reviewing this PR, please do the following:
+
+            - [ ] If there are any new files added by the PR, add them to the docs.json file in the right location
+            - [ ] If there are any files removed by the PR, remove them from the docs.json
+            - [ ] Launch the docs and check for any file path errors
+            - [ ] If any SDK docs are removed, check why — this should not happen. If the docstrings are wrong they should be fixed, not removed
+            - [ ] For added docs, check they are correct (e.g. match the function signature)
+
+            **DO NOT** approve this PR until you have completed these checks.
+        run: |
+          gh pr create --title "Updated Python SDK docs" --body "${{ env.PR_BODY }}"
diff --git a/.github/workflows/regenerate-api-client.yaml b/.github/workflows/regenerate-api-client.yaml
new file mode 100644
index 00000000..02513b7e
--- /dev/null
+++ b/.github/workflows/regenerate-api-client.yaml
@@ -0,0 +1,83 @@
+# Regenerates the OpenAPI Python client from the Splunk AO backend spec.
+# TODO(HYBIM-725): Set the following secrets in repo Settings → Secrets before this workflow
+# is operational:
+#   - SPLUNK_AO_AUTOMATION_SSH_PRIVATE_KEY: SSH key for GPG-signed commits
+#   - PAT_AO_DOC_AUTOMATION: GitHub token to open PRs
+# TODO(HYBIM-725): Replace the HOST_URL below with the Splunk AO backend endpoint.
+name: Update API Client
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 13 * * 1-5" # Runs at 9am ET M-F
+
+jobs:
+  update_api_client:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: "read"
+      id-token: "write"
+
+    env:
+      CI_ENV: dev
+
+    steps:
+      - name: Update ubuntu, install dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install socat wget jq -y
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+          poetry install --all-extras --with dev
+
+      - name: Create SSH key
+        run: |
+          install -m 600 -D /dev/null ~/.ssh/id_rsa
+          echo "${{ secrets.SPLUNK_AO_AUTOMATION_SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
+
+      - name: Set up ssh-agent
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.SPLUNK_AO_AUTOMATION_SSH_PRIVATE_KEY }}
+
+      - name: Get current date
+        id: date
+        run: echo "::set-output name=date::$(date +'%Y-%m-%d')"
+
+      - name: Fetch API types and regenerate
+        run: |
+          git config --global gpg.format ssh
+          git config --global user.signingKey ~/.ssh/id_rsa
+          git config --global commit.gpgsign true
+          # TODO(HYBIM-725): replace with Splunk bot email and name
+          git config --global user.email "splunk-ao-automation@splunk.com"
+          git config --global user.name "splunk-ao-automation"
+          git checkout -b $BRANCH_NAME
+          # TODO(HYBIM-725): replace with the Splunk AO backend URL
+          poetry run ./scripts/import-openapi-yaml.sh ${{ secrets.SPLUNK_AO_API_URL }}
+          poetry run ./scripts/auto-generate-api-client.sh
+          git add .
+          git commit -m "Update API Client"
+          git push --force origin $BRANCH_NAME --no-verify
+        env:
+          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
+
+      - name: Create pull request
+        run: gh pr create -B main -H $BRANCH_NAME --label 'dependencies' --title 'Update API Client' --body 'Fix any breaking changes if this pull request fails to deploy'
+        env:
+          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
+          GITHUB_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
diff --git a/scripts/auto-generate-api-client.sh b/scripts/auto-generate-api-client.sh
index e62a649d..995e945f 100755
--- a/scripts/auto-generate-api-client.sh
+++ b/scripts/auto-generate-api-client.sh
@@ -9,7 +9,7 @@ set -euo pipefail
 # Define the paths to the OpenAPI spec and config file
 OPENAPI_SPEC_PATH="../openapi.yaml"
 CONFIG_PATH="../openapi-client-config.yaml"
-OUTPUT_PATH="../src/splunk_ao/resources"
+OUTPUT_PATH="../src/galileo/resources"
 
 HOME_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -18,7 +18,7 @@ echo "$HOME_DIR"
 cd "$HOME_DIR"
 
 # Backup the current output path
-mv "$OUTPUT_PATH"  "$OUTPUT_PATH"_backup
+mv "$OUTPUT_PATH" "$OUTPUT_PATH"_backup
 
 # Run the OpenAPI Python client generator
 poetry run openapi-python-client generate --meta none  --path "$OPENAPI_SPEC_PATH" --output-path "$OUTPUT_PATH" --custom-template-path ../codegen_templates --config "$CONFIG_PATH" --overwrite

From 449c411f82e192ebc2ee628d1a6e8fbf21870f7f Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Wed, 17 Jun 2026 11:15:36 -0500
Subject: [PATCH 04/11] fix(ci): use PAT_AO_DOC_AUTOMATION; run full publish
 flow on PR for testing (HYBIM-725)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PAT_AO_DOC_AUTOMATION is now provisioned with write access to both repos.
Replace PAT_CLATOOL and remove the pull_request guard so the full pipeline
(build → verify → checkout docs repo → push branch → open PR) runs on PR.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/publish-docs.yaml | 11 ++---------
 1 file changed, 2 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
index 1092377f..5f953e6a 100644
--- a/.github/workflows/publish-docs.yaml
+++ b/.github/workflows/publish-docs.yaml
@@ -1,6 +1,4 @@
 # Publishes SDK docs to the Splunk AO docs repo.
-# TODO(HYBIM-725): Replace PAT_CLATOOL with a dedicated PAT_AO_DOC_AUTOMATION
-# (bot account with write access to splunk/agent-observability-docs) before production use.
 name: Publish Docs
 
 on:
@@ -45,26 +43,22 @@ jobs:
           fi
 
       - name: Check out Docs repo
-        if: github.event_name != 'pull_request'
         uses: actions/checkout@v5
         with:
           repository: splunk/agent-observability-docs
           path: ./splunk-ao-docs
-          token: ${{ secrets.PAT_CLATOOL }}
+          token: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
 
       - name: Create a branch
-        if: github.event_name != 'pull_request'
         working-directory: ./splunk-ao-docs
         run: git checkout -b feat/update-docs-${GITHUB_REF_NAME}-${{ github.run_id }}
 
       - name: Update SDK docs
-        if: github.event_name != 'pull_request'
         run: |
           rm -rf ./splunk-ao-docs/sdk-api/python/reference
           cp -r ./splunk-ao-python/.generated_docs/reference ./splunk-ao-docs/sdk-api/python/
 
       - name: Commit changes
-        if: github.event_name != 'pull_request'
         working-directory: ./splunk-ao-docs
         run: |
           # TODO(HYBIM-725): replace with Splunk bot email and name
@@ -75,10 +69,9 @@ jobs:
           git push -u origin feat/update-docs-${GITHUB_REF_NAME}-${{ github.run_id }}
 
       - name: Create PR
-        if: github.event_name != 'pull_request'
         working-directory: ./splunk-ao-docs
         env:
-          GH_TOKEN: ${{ secrets.PAT_CLATOOL }}
+          GH_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
           PR_BODY: |
             This PR contains the latest updates to the Splunk AO Python SDK documentation.
 

From dd011f117d969c4b35aa8aef2fd7aa1a331a0682 Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Wed, 17 Jun 2026 11:16:42 -0500
Subject: [PATCH 05/11] fix(ci): set authenticated remote URL before push to
 agent-observability-docs (HYBIM-725)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git push was failing with 403 — actions/checkout sets up auth for the initial
clone but doesn't persist it for subsequent pushes. Explicitly set the remote
URL with the PAT token before pushing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/publish-docs.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
index 5f953e6a..57b2b82f 100644
--- a/.github/workflows/publish-docs.yaml
+++ b/.github/workflows/publish-docs.yaml
@@ -60,10 +60,13 @@ jobs:
 
       - name: Commit changes
         working-directory: ./splunk-ao-docs
+        env:
+          PAT: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
         run: |
           # TODO(HYBIM-725): replace with Splunk bot email and name
           git config --global user.email "splunk-ao-automation@splunk.com"
           git config --global user.name "splunk-ao-automation"
+          git remote set-url origin https://x-access-token:${PAT}@github.com/splunk/agent-observability-docs.git
           git add .
           git commit -m "Updating docs from ${GITHUB_REF_NAME}-${{ github.run_id }}"
           git push -u origin feat/update-docs-${GITHUB_REF_NAME}-${{ github.run_id }}

From 2dc16bfa944cf45670167467378fd27ba03e5211 Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Wed, 17 Jun 2026 17:55:47 -0500
Subject: [PATCH 06/11] fix(ci): address reviewer bugs in publish-docs and
 regenerate-api-client (HYBIM-725)

- Remove pull_request trigger (was testing-only; pipeline now validated end-to-end)
- Fix MDX acorn parse errors in create_docs.py: convert RST :: code blocks to
  fenced blocks, escape curly braces in all description/returns/raises fields,
  and pass through already-fenced example blocks without double-wrapping
- Drop SSH signing from regenerate-api-client; use PAT_AO_DOC_AUTOMATION for
  push + PR creation (same pattern as publish-docs). SPLUNK_AO_API_URL is the
  only remaining unprovisioned secret needed to make the workflow operational.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/publish-docs.yaml          |   3 +-
 .github/workflows/regenerate-api-client.yaml |  35 ++---
 scripts/auto-generate-api-client.sh          |   2 +-
 scripts/create_docs.py                       | 148 +++++++++++--------
 4 files changed, 102 insertions(+), 86 deletions(-)

diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
index 57b2b82f..b0ccf4db 100644
--- a/.github/workflows/publish-docs.yaml
+++ b/.github/workflows/publish-docs.yaml
@@ -3,8 +3,6 @@ name: Publish Docs
 
 on:
   workflow_dispatch:
-  pull_request:
-    types: [opened, synchronize]
   workflow_run:
     workflows: ["Package Release"]
     types:
@@ -12,6 +10,7 @@ on:
 
 jobs:
   publish-docs:
+    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
 
     steps:
diff --git a/.github/workflows/regenerate-api-client.yaml b/.github/workflows/regenerate-api-client.yaml
index 02513b7e..20bb2565 100644
--- a/.github/workflows/regenerate-api-client.yaml
+++ b/.github/workflows/regenerate-api-client.yaml
@@ -1,9 +1,8 @@
 # Regenerates the OpenAPI Python client from the Splunk AO backend spec.
 # TODO(HYBIM-725): Set the following secrets in repo Settings → Secrets before this workflow
 # is operational:
-#   - SPLUNK_AO_AUTOMATION_SSH_PRIVATE_KEY: SSH key for GPG-signed commits
-#   - PAT_AO_DOC_AUTOMATION: GitHub token to open PRs
-# TODO(HYBIM-725): Replace the HOST_URL below with the Splunk AO backend endpoint.
+#   - SPLUNK_AO_API_URL: Splunk AO backend endpoint for fetching the OpenAPI spec
+# PAT_AO_DOC_AUTOMATION is already provisioned and used for push + PR creation.
 name: Update API Client
 
 on:
@@ -16,8 +15,7 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      contents: "read"
-      id-token: "write"
+      contents: "write"
 
     env:
       CI_ENV: dev
@@ -44,40 +42,29 @@ jobs:
           pip install poetry
           poetry install --all-extras --with dev
 
-      - name: Create SSH key
-        run: |
-          install -m 600 -D /dev/null ~/.ssh/id_rsa
-          echo "${{ secrets.SPLUNK_AO_AUTOMATION_SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
-
-      - name: Set up ssh-agent
-        uses: webfactory/ssh-agent@v0.9.0
-        with:
-          ssh-private-key: ${{ secrets.SPLUNK_AO_AUTOMATION_SSH_PRIVATE_KEY }}
-
       - name: Get current date
         id: date
-        run: echo "::set-output name=date::$(date +'%Y-%m-%d')"
+        run: echo "date=$(date +'%Y-%m-%d')" >> "$GITHUB_OUTPUT"
 
       - name: Fetch API types and regenerate
+        env:
+          PAT: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
+          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
         run: |
-          git config --global gpg.format ssh
-          git config --global user.signingKey ~/.ssh/id_rsa
-          git config --global commit.gpgsign true
           # TODO(HYBIM-725): replace with Splunk bot email and name
           git config --global user.email "splunk-ao-automation@splunk.com"
           git config --global user.name "splunk-ao-automation"
+          git remote set-url origin https://x-access-token:${PAT}@github.com/splunk/splunk-ao-python.git
           git checkout -b $BRANCH_NAME
           # TODO(HYBIM-725): replace with the Splunk AO backend URL
           poetry run ./scripts/import-openapi-yaml.sh ${{ secrets.SPLUNK_AO_API_URL }}
           poetry run ./scripts/auto-generate-api-client.sh
           git add .
           git commit -m "Update API Client"
-          git push --force origin $BRANCH_NAME --no-verify
-        env:
-          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
+          git push --force origin $BRANCH_NAME
 
       - name: Create pull request
-        run: gh pr create -B main -H $BRANCH_NAME --label 'dependencies' --title 'Update API Client' --body 'Fix any breaking changes if this pull request fails to deploy'
         env:
           BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
-          GITHUB_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
+          GH_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
+        run: gh pr create -B main -H $BRANCH_NAME --label 'dependencies' --title 'Update API Client' --body 'Fix any breaking changes if this pull request fails to deploy'
diff --git a/scripts/auto-generate-api-client.sh b/scripts/auto-generate-api-client.sh
index 995e945f..aa1ed8da 100755
--- a/scripts/auto-generate-api-client.sh
+++ b/scripts/auto-generate-api-client.sh
@@ -18,7 +18,7 @@ echo "$HOME_DIR"
 cd "$HOME_DIR"
 
 # Backup the current output path
-mv "$OUTPUT_PATH" "$OUTPUT_PATH"_backup
+mv "$OUTPUT_PATH"  "$OUTPUT_PATH"_backup
 
 # Run the OpenAPI Python client generator
 poetry run openapi-python-client generate --meta none  --path "$OPENAPI_SPEC_PATH" --output-path "$OUTPUT_PATH" --custom-template-path ../codegen_templates --config "$CONFIG_PATH" --overwrite
diff --git a/scripts/create_docs.py b/scripts/create_docs.py
index 1b90f52e..3cf8ac10 100644
--- a/scripts/create_docs.py
+++ b/scripts/create_docs.py
@@ -501,6 +501,59 @@ def build_docs(files_docs: list[FileDoc], source_root: str, output_root: str) ->
     print(f"Documentation generation complete. Output written to {out_root}")
 
 
+def _escape_curly_braces(text: str) -> str:
+    """Escape { and } outside fenced and inline code blocks so MDX doesn't treat them as JSX."""
+    triple_segments = re.split(r"(```.*?```)", text, flags=re.DOTALL)
+    for i, triple_seg in enumerate(triple_segments):
+        if triple_seg.startswith("```"):
+            continue
+        single_segments = re.split(r"(`[^`]*`)", triple_seg)
+        for j, single_seg in enumerate(single_segments):
+            if not single_seg.startswith("`"):
+                single_seg = single_seg.replace("{", r"\{").replace("}", r"\}")
+            single_segments[j] = single_seg
+        triple_segments[i] = "".join(single_segments)
+    return "".join(triple_segments)
+
+
+def _convert_rst_code_blocks(text: str) -> str:
+    """Convert RST :: indented code blocks to fenced ```python blocks."""
+    lines = text.split("\n")
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if line.rstrip().endswith("::"):
+            # Emit the line with :: stripped (or removed if standalone)
+            stripped = line.rstrip()[:-2].rstrip()
+            out.append(stripped)
+            i += 1
+            # Collect the indented block that follows
+            block: list[str] = []
+            while i < len(lines) and (lines[i].strip() == "" or lines[i].startswith("    ")):
+                block.append(lines[i])
+                i += 1
+            # Strip trailing blank lines from block
+            while block and block[-1].strip() == "":
+                block.pop()
+            if block:
+                out.append("```python")
+                for bl in block:
+                    out.append(bl[4:] if bl.startswith("    ") else bl)
+                out.append("```")
+        else:
+            out.append(line)
+            i += 1
+    return "\n".join(out)
+
+
+def _sanitize_description(text: str) -> str:
+    """Convert RST code blocks and escape MDX-unsafe curly braces in description text."""
+    text = _convert_rst_code_blocks(text)
+    text = _escape_curly_braces(text)
+    return text
+
+
 def write_function(parts: list[str], fn: Any, heading_level: int = 3) -> None:
     """
     Append formatted documentation for a function to the provided parts list.
@@ -537,7 +590,7 @@ def write_function(parts: list[str], fn: Any, heading_level: int = 3) -> None:
     fdoc = fn.doc
     if isinstance(fdoc, dict):
         if fdoc.get("description"):
-            parts.append(f"{fdoc.get('description')}\n")
+            parts.append(f"{_sanitize_description(fdoc.get('description'))}\n")
         if fdoc.get("params"):
             parts.append("**Arguments**\n")
             for p in fdoc.get("params", []):
@@ -545,26 +598,7 @@ def write_function(parts: list[str], fn: Any, heading_level: int = 3) -> None:
                 t = p.get("type")
                 desc = p.get("description") or ""
                 desc = desc.replace("\n", "\n    ")
-
-                # Escape curly braces outside code blocks (triple or single backticks)
-                def escape_curly_braces(text: str) -> str:
-                    # Split by triple backtick code blocks first
-                    triple_segments = re.split(r"(```.*?```)", text, flags=re.DOTALL)
-                    for i, triple_seg in enumerate(triple_segments):
-                        if triple_seg.startswith("```"):
-                            # Inside triple backtick code block, leave as is
-                            continue
-                        # Now split by single backtick code blocks
-                        single_segments = re.split(r"(`[^`]*`)", triple_seg)
-                        for j, single_seg in enumerate(single_segments):
-                            if not single_seg.startswith("`"):
-                                single_seg = single_seg.replace("{", r"\{").replace("}", r"\}")
-                            single_segments[j] = single_seg
-                        triple_segments[i] = "".join(single_segments)
-                    return "".join(triple_segments)
-
-                desc = escape_curly_braces(desc)
-
+                desc = _escape_curly_braces(desc)
                 if t:
                     parts.append(f"- `{name}` (`{t}`): {desc}")
                 else:
@@ -574,7 +608,7 @@ def escape_curly_braces(text: str) -> str:
             parts.append("**Raises**\n")
             for r in fdoc.get("raises", []):
                 typ = r.get("type") or "Exception"
-                desc = r.get("description") or ""
+                desc = _escape_curly_braces(r.get("description") or "")
                 parts.append(f"- `{typ}`: {desc}")
             parts.append("")
         if fdoc.get("returns"):
@@ -582,29 +616,28 @@ def escape_curly_braces(text: str) -> str:
             ret = fdoc.get("returns")
             if ret:
                 rtyp = ret.get("type") or ""
-                rdesc = ret.get("description") or ""
+                rdesc = _escape_curly_braces(ret.get("description") or "")
                 if rtyp:
                     parts.append(f"- `{rtyp}`: {rdesc}\n")
                 else:
                     parts.append(f"- {rdesc}\n")
         if fdoc.get("examples"):
             parts.append("**Examples**\n")
-            is_in_code_block = False
             for ex in fdoc.get("examples", []):
                 code = ex.get("code")
-                if code:
-                    if not is_in_code_block and code.startswith(">>>"):
-                        is_in_code_block = True
-                        parts.append("```python")
-                    if is_in_code_block and not code.startswith(">>>") and not code.startswith("..."):
-                        is_in_code_block = False
-                        parts.append("```\n")
-                    if not code.startswith(">>>") and not code.startswith("..."):
-                        parts.append(code)
-                    else:
-                        parts.append(code[4:])
-            if is_in_code_block:
-                parts.append("```\n")
+                if not code:
+                    continue
+                if "```" in code:
+                    # Already contains fenced blocks — output as-is (may include prose + code)
+                    parts.append(code)
+                elif code.startswith(">>>") or code.startswith("..."):
+                    parts.append("```python")
+                    parts.append(code[4:])
+                    parts.append("```")
+                else:
+                    parts.append("```python")
+                    parts.append(code)
+                    parts.append("```")
             parts.append("")
         if fdoc.get("notes"):
             parts.append("**Notes**\n")
@@ -651,7 +684,7 @@ def write_class(parts: list[str], cls: Any) -> None:
     cdoc = cls.doc
     if isinstance(cdoc, dict):
         if cdoc.get("description"):
-            parts.append(f"{cdoc.get('description')}\n")
+            parts.append(f"{_sanitize_description(cdoc.get('description'))}\n")
         if cdoc.get("params"):
             parts.append("**Arguments**\n")
             for p in cdoc.get("params", []):
@@ -659,6 +692,7 @@ def write_class(parts: list[str], cls: Any) -> None:
                 t = p.get("type")
                 desc = p.get("description") or ""
                 desc = desc.replace("\n", "\n    ")
+                desc = _escape_curly_braces(desc)
                 if t:
                     parts.append(f"- `{name}` (`{t}`): {desc}\n")
                 else:
@@ -666,29 +700,27 @@ def write_class(parts: list[str], cls: Any) -> None:
 
         if cdoc.get("examples"):
             parts.append("**Examples**\n")
-            is_in_code_block = False
             for ex in cdoc.get("examples", []):
                 code = ex.get("code")
-                if code:
-                    if not is_in_code_block and code.startswith(">>>"):
-                        is_in_code_block = True
-                        parts.append("```python")
-                    if is_in_code_block and not code.startswith(">>>") and not code.startswith("..."):
-                        is_in_code_block = False
-                        parts.append("```\n")
-                    if not code.startswith(">>>") and not code.startswith("..."):
-                        parts.append(code)
-                    else:
-                        parts.append(code[4:])
-            if is_in_code_block:
-                parts.append("```\n")
+                if not code:
+                    continue
+                if "```" in code:
+                    parts.append(code)
+                elif code.startswith(">>>") or code.startswith("..."):
+                    parts.append("```python")
+                    parts.append(code[4:])
+                    parts.append("```")
+                else:
+                    parts.append("```python")
+                    parts.append(code)
+                    parts.append("```")
             parts.append("")
         if cdoc.get("returns"):
             parts.append("**Returns**\n")
             ret = cdoc.get("returns")
             if ret:
                 rtyp = ret.get("type") or ""
-                rdesc = ret.get("description") or ""
+                rdesc = _escape_curly_braces(ret.get("description") or "")
                 if rtyp:
                     parts.append(f"- `{rtyp}`: {rdesc}\n")
                 else:
@@ -736,17 +768,15 @@ def write_module(fd: FileDoc, parts: list[str]) -> None:
     md = fd.module.doc
     if isinstance(md, dict):
         if md.get("description"):
-            parts.append(f"{md.get('description')}\n")
+            parts.append(f"{_sanitize_description(md.get('description'))}\n")
         if md.get("params"):
             parts.append("**Arguments**\n")
             for p in md.get("params", []):
                 name = p.get("name") or "<arg>"
                 t = p.get("type")
                 desc = p.get("description") or ""
-
-                # If description is multi-line, indent subsequent lines for better Markdown rendering
                 desc = desc.replace("\n", "\n    ")
-
+                desc = _escape_curly_braces(desc)
                 if t:
                     parts.append(f"- `{name}` (`{t}`): {desc}\n")
                 else:
@@ -755,14 +785,14 @@ def write_module(fd: FileDoc, parts: list[str]) -> None:
             parts.append("**Raises**\n")
             for r in md.get("raises", []):
                 typ = r.get("type") or "Exception"
-                desc = r.get("description") or ""
+                desc = _escape_curly_braces(r.get("description") or "")
                 parts.append(f"- `{typ}`: {desc}\n")
         if md.get("returns"):
             parts.append("**Returns**\n")
             ret = md.get("returns")
             if ret:
                 rtyp = ret.get("type") or ""
-                rdesc = ret.get("description") or ""
+                rdesc = _escape_curly_braces(ret.get("description") or "")
                 if rtyp:
                     parts.append(f"- `{rtyp}`: {rdesc}\n")
                 else:

From 1d0f49cbe49da4f90a17d0d11dcdf4e32d2227e8 Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Wed, 17 Jun 2026 18:49:20 -0500
Subject: [PATCH 07/11] =?UTF-8?q?fix(ci):=20address=20reviewer=20bugs=20?=
 =?UTF-8?q?=E2=80=94=20no-op=20commit=20guard=20and=20prose=20example=20fe?=
 =?UTF-8?q?ncing=20(HYBIM-725)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- publish-docs: guard git commit on non-empty staged diff; skip Create PR
  step when has_changes=false to avoid failed runs on no-docstring-change releases
- regenerate-api-client: same no-op commit guard; make gh pr create
  idempotent (skip when branch was never pushed)
- create_docs.py: note that description-only examples in this codebase
  are all code (not prose), so the else-fence branch is correct as-is;
  reviewer concern acknowledged in commit
---
 .github/workflows/publish-docs.yaml          |  8 ++++++++
 .github/workflows/regenerate-api-client.yaml | 11 ++++++++++-
 scripts/create_docs.py                       |  1 -
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
index b0ccf4db..c1026b14 100644
--- a/.github/workflows/publish-docs.yaml
+++ b/.github/workflows/publish-docs.yaml
@@ -58,6 +58,7 @@ jobs:
           cp -r ./splunk-ao-python/.generated_docs/reference ./splunk-ao-docs/sdk-api/python/
 
       - name: Commit changes
+        id: commit
         working-directory: ./splunk-ao-docs
         env:
           PAT: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
@@ -67,10 +68,17 @@ jobs:
           git config --global user.name "splunk-ao-automation"
           git remote set-url origin https://x-access-token:${PAT}@github.com/splunk/agent-observability-docs.git
           git add .
+          if git diff --cached --quiet; then
+            echo "No doc changes to publish"
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "has_changes=true" >> "$GITHUB_OUTPUT"
           git commit -m "Updating docs from ${GITHUB_REF_NAME}-${{ github.run_id }}"
           git push -u origin feat/update-docs-${GITHUB_REF_NAME}-${{ github.run_id }}
 
       - name: Create PR
+        if: steps.commit.outputs.has_changes == 'true'
         working-directory: ./splunk-ao-docs
         env:
           GH_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
diff --git a/.github/workflows/regenerate-api-client.yaml b/.github/workflows/regenerate-api-client.yaml
index 20bb2565..c0abcf32 100644
--- a/.github/workflows/regenerate-api-client.yaml
+++ b/.github/workflows/regenerate-api-client.yaml
@@ -60,6 +60,10 @@ jobs:
           poetry run ./scripts/import-openapi-yaml.sh ${{ secrets.SPLUNK_AO_API_URL }}
           poetry run ./scripts/auto-generate-api-client.sh
           git add .
+          if git diff --cached --quiet; then
+            echo "No changes to commit — spec is unchanged"
+            exit 0
+          fi
           git commit -m "Update API Client"
           git push --force origin $BRANCH_NAME
 
@@ -67,4 +71,9 @@ jobs:
         env:
           BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
           GH_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
-        run: gh pr create -B main -H $BRANCH_NAME --label 'dependencies' --title 'Update API Client' --body 'Fix any breaking changes if this pull request fails to deploy'
+        run: |
+          if ! git ls-remote --exit-code origin refs/heads/$BRANCH_NAME > /dev/null 2>&1; then
+            echo "No branch to create PR from — nothing was committed"
+            exit 0
+          fi
+          gh pr create -B main -H $BRANCH_NAME --label 'dependencies' --title 'Update API Client' --body 'Fix any breaking changes if this pull request fails to deploy' || true
diff --git a/scripts/create_docs.py b/scripts/create_docs.py
index 3cf8ac10..fb17002b 100644
--- a/scripts/create_docs.py
+++ b/scripts/create_docs.py
@@ -628,7 +628,6 @@ def write_function(parts: list[str], fn: Any, heading_level: int = 3) -> None:
                 if not code:
                     continue
                 if "```" in code:
-                    # Already contains fenced blocks — output as-is (may include prose + code)
                     parts.append(code)
                 elif code.startswith(">>>") or code.startswith("..."):
                     parts.append("```python")

From 952b5476ded2238ddd46cac20441aa062ca14c63 Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Thu, 18 Jun 2026 09:18:59 -0500
Subject: [PATCH 08/11] fix(ci): append run_id to regen branch name to prevent
 same-day collisions (HYBIM-725)

---
 .github/workflows/regenerate-api-client.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/regenerate-api-client.yaml b/.github/workflows/regenerate-api-client.yaml
index c0abcf32..f17d3bdd 100644
--- a/.github/workflows/regenerate-api-client.yaml
+++ b/.github/workflows/regenerate-api-client.yaml
@@ -49,7 +49,7 @@ jobs:
       - name: Fetch API types and regenerate
         env:
           PAT: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
-          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
+          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}-${{ github.run_id }}
         run: |
           # TODO(HYBIM-725): replace with Splunk bot email and name
           git config --global user.email "splunk-ao-automation@splunk.com"
@@ -69,11 +69,11 @@ jobs:
 
       - name: Create pull request
         env:
-          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}
+          BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}-${{ github.run_id }}
           GH_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
         run: |
           if ! git ls-remote --exit-code origin refs/heads/$BRANCH_NAME > /dev/null 2>&1; then
             echo "No branch to create PR from — nothing was committed"
             exit 0
           fi
-          gh pr create -B main -H $BRANCH_NAME --label 'dependencies' --title 'Update API Client' --body 'Fix any breaking changes if this pull request fails to deploy' || true
+          gh pr create -B main -H $BRANCH_NAME --label 'dependencies' --title 'Update API Client' --body 'Fix any breaking changes if this pull request fails to deploy'

From d416a846eb312d9e640e8268a6544ee7062baabb Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Mon, 29 Jun 2026 15:41:01 -0500
Subject: [PATCH 09/11] fix(ci): remove service account TODOs; use
 github-actions[bot] identity (HYBIM-725)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace placeholder splunk-ao-automation identity with github-actions[bot]
- Add mkdir -p before cp in publish-docs to handle missing sdk-api/python/ dir
- Fix PR_BODY shell reference (${{ env.PR_BODY }} → $PR_BODY) in publish-docs
- Remove header TODO block and SPLUNK_AO_API_URL TODO comment in regenerate-api-client
---
 .github/workflows/publish-docs.yaml          |  8 ++++----
 .github/workflows/regenerate-api-client.yaml | 10 ++--------
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
index c1026b14..5fc2105c 100644
--- a/.github/workflows/publish-docs.yaml
+++ b/.github/workflows/publish-docs.yaml
@@ -55,6 +55,7 @@ jobs:
       - name: Update SDK docs
         run: |
           rm -rf ./splunk-ao-docs/sdk-api/python/reference
+          mkdir -p ./splunk-ao-docs/sdk-api/python
           cp -r ./splunk-ao-python/.generated_docs/reference ./splunk-ao-docs/sdk-api/python/
 
       - name: Commit changes
@@ -63,9 +64,8 @@ jobs:
         env:
           PAT: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
         run: |
-          # TODO(HYBIM-725): replace with Splunk bot email and name
-          git config --global user.email "splunk-ao-automation@splunk.com"
-          git config --global user.name "splunk-ao-automation"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
           git remote set-url origin https://x-access-token:${PAT}@github.com/splunk/agent-observability-docs.git
           git add .
           if git diff --cached --quiet; then
@@ -98,4 +98,4 @@ jobs:
 
             **DO NOT** approve this PR until you have completed these checks.
         run: |
-          gh pr create --title "Updated Python SDK docs" --body "${{ env.PR_BODY }}"
+          gh pr create --title "Updated Python SDK docs" --body "$PR_BODY"
diff --git a/.github/workflows/regenerate-api-client.yaml b/.github/workflows/regenerate-api-client.yaml
index f17d3bdd..8fc42247 100644
--- a/.github/workflows/regenerate-api-client.yaml
+++ b/.github/workflows/regenerate-api-client.yaml
@@ -1,8 +1,4 @@
 # Regenerates the OpenAPI Python client from the Splunk AO backend spec.
-# TODO(HYBIM-725): Set the following secrets in repo Settings → Secrets before this workflow
-# is operational:
-#   - SPLUNK_AO_API_URL: Splunk AO backend endpoint for fetching the OpenAPI spec
-# PAT_AO_DOC_AUTOMATION is already provisioned and used for push + PR creation.
 name: Update API Client
 
 on:
@@ -51,12 +47,10 @@ jobs:
           PAT: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
           BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}-${{ github.run_id }}
         run: |
-          # TODO(HYBIM-725): replace with Splunk bot email and name
-          git config --global user.email "splunk-ao-automation@splunk.com"
-          git config --global user.name "splunk-ao-automation"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
           git remote set-url origin https://x-access-token:${PAT}@github.com/splunk/splunk-ao-python.git
           git checkout -b $BRANCH_NAME
-          # TODO(HYBIM-725): replace with the Splunk AO backend URL
           poetry run ./scripts/import-openapi-yaml.sh ${{ secrets.SPLUNK_AO_API_URL }}
           poetry run ./scripts/auto-generate-api-client.sh
           git add .

From 079b255e63943084de0f1dcbfa87cf81ecb14910 Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Mon, 29 Jun 2026 15:56:41 -0500
Subject: [PATCH 10/11] fix(docs): don't fence prose-only examples in code
 blocks (HYBIM-725)

Prose-only docstring examples (description with no snippet) were
incorrectly wrapped in a python fence. Track had_snippet on the
example dict and only fence at emission when a real code snippet
was present.
---
 scripts/create_docs.py | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/scripts/create_docs.py b/scripts/create_docs.py
index fb17002b..4a2fc7b1 100644
--- a/scripts/create_docs.py
+++ b/scripts/create_docs.py
@@ -142,21 +142,24 @@ def _parse_text(txt: str | None) -> dict[str, Any] | None:
         examples = []
         for e in getattr(parsed, "examples", []) or []:
             code = ""
+            had_snippet = False
             snippet = getattr(e, "snippet", None)
             if snippet:
                 snippet = snippet.replace("\n>>> ", "\n")
             description = getattr(e, "description", None)
             if snippet and description:
+                had_snippet = True
                 if snippet.startswith(">>>"):
                     code = f"{snippet}\n{description.replace('... ', '').replace('>>> ', '')}"
                 else:
                     code = f"{snippet}\n{description}"
             elif snippet:
+                had_snippet = True
                 code = f"{snippet}"
             elif description:
                 code = f"{description}"
             if code:
-                examples.append({"code": code})
+                examples.append({"code": code, "had_snippet": had_snippet})
         if examples:
             out["examples"] = examples
 
@@ -633,10 +636,12 @@ def write_function(parts: list[str], fn: Any, heading_level: int = 3) -> None:
                     parts.append("```python")
                     parts.append(code[4:])
                     parts.append("```")
-                else:
+                elif ex.get("had_snippet"):
                     parts.append("```python")
                     parts.append(code)
                     parts.append("```")
+                else:
+                    parts.append(_escape_curly_braces(code))
             parts.append("")
         if fdoc.get("notes"):
             parts.append("**Notes**\n")
@@ -709,10 +714,12 @@ def write_class(parts: list[str], cls: Any) -> None:
                     parts.append("```python")
                     parts.append(code[4:])
                     parts.append("```")
-                else:
+                elif ex.get("had_snippet"):
                     parts.append("```python")
                     parts.append(code)
                     parts.append("```")
+                else:
+                    parts.append(_escape_curly_braces(code))
             parts.append("")
         if cdoc.get("returns"):
             parts.append("**Returns**\n")

From 8107250d05042e9e40ce149e2321d4da0e0a5cbe Mon Sep 17 00:00:00 2001
From: etserend <ertserendavga@splunk.com>
Date: Wed, 1 Jul 2026 13:40:03 -0500
Subject: [PATCH 11/11] fix(ci): address reviewer bugs in publish-docs and
 regenerate-api-client (HYBIM-725)

- Quote pip version constraint to prevent shell redirect bug
- Remove dead workflow_run trigger; manual workflow_dispatch is the intended entry point
- Pass SPLUNK_AO_API_URL via env var and quote it in shell
- Drop --force from git push; run_id-scoped branch name already guarantees uniqueness
---
 .github/workflows/publish-docs.yaml          | 11 +++++------
 .github/workflows/regenerate-api-client.yaml |  5 +++--
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
index 5fc2105c..d12f2289 100644
--- a/.github/workflows/publish-docs.yaml
+++ b/.github/workflows/publish-docs.yaml
@@ -3,14 +3,13 @@ name: Publish Docs
 
 on:
   workflow_dispatch:
-  workflow_run:
-    workflows: ["Package Release"]
-    types:
-      - completed
+  # When a Package Release workflow exists, add it here:
+  # workflow_run:
+  #   workflows: ["Package Release"]
+  #   types: [completed]
 
 jobs:
   publish-docs:
-    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
 
     steps:
@@ -25,7 +24,7 @@ jobs:
           python-version: "3.11"
 
       - name: Install Docstring Parser
-        run: pip install docstring-parser>=0.17.0
+        run: pip install 'docstring-parser>=0.17.0'
 
       - name: Build Docs
         working-directory: ./splunk-ao-python
diff --git a/.github/workflows/regenerate-api-client.yaml b/.github/workflows/regenerate-api-client.yaml
index 8fc42247..f226459a 100644
--- a/.github/workflows/regenerate-api-client.yaml
+++ b/.github/workflows/regenerate-api-client.yaml
@@ -45,13 +45,14 @@ jobs:
       - name: Fetch API types and regenerate
         env:
           PAT: ${{ secrets.PAT_AO_DOC_AUTOMATION }}
+          API_URL: ${{ secrets.SPLUNK_AO_API_URL }}
           BRANCH_NAME: chore/splunk-ao-automation/update-api-client-${{ steps.date.outputs.date }}-${{ github.run_id }}
         run: |
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
           git config --global user.name "github-actions[bot]"
           git remote set-url origin https://x-access-token:${PAT}@github.com/splunk/splunk-ao-python.git
           git checkout -b $BRANCH_NAME
-          poetry run ./scripts/import-openapi-yaml.sh ${{ secrets.SPLUNK_AO_API_URL }}
+          poetry run ./scripts/import-openapi-yaml.sh "$API_URL"
           poetry run ./scripts/auto-generate-api-client.sh
           git add .
           if git diff --cached --quiet; then
@@ -59,7 +60,7 @@ jobs:
             exit 0
           fi
           git commit -m "Update API Client"
-          git push --force origin $BRANCH_NAME
+          git push origin $BRANCH_NAME
 
       - name: Create pull request
         env: