feat(docs): wire splunk-ao SDK reference doc auto-generation (HYBIM-725)

[etserend]

Summary

Wires the splunk-ao SDK reference doc auto-generation pipeline for the Splunk AO rebrand. Updates source paths in the doc-gen configs and scripts, adds two new GitHub Actions workflows, and fixes a premature OUTPUT_PATH rename.

Changes

File	Change
pydoc-markdown-handlers.yml	Comment: "Galileo handlers" → "Splunk AO handlers"; search_path already pointed to ./src/splunk_ao/handlers (landed via HYBIM-717)
scripts/auto-generate-api-client.sh	Reverted premature OUTPUT_PATH to ../src/galileo/resources — src/galileo/resources still exists and splunk_ao imports from it via the compat shim; path moves when resources are migrated
.github/workflows/publish-docs.yaml	New — triggers on release or workflow_dispatch; runs create_docs.py, opens PR against splunk/agent-observability-docs with generated .mdx files
.github/workflows/regenerate-api-client.yaml	New — daily cron + manual dispatch; regenerates API client from OpenAPI spec and opens PR

Note on pydoc-markdown.yml and scripts/create_docs.py

Both files already point to src/splunk_ao — those changes landed on main as part of HYBIM-717 and are not part of this diff.

Out of scope

• Docstring content updates — covered by HYBIM-726
• scripts/import-openapi-yaml.sh logic — HOST_URL is a runtime arg; galileo_core__schemas__* yq keys are from the external galileo-core package and must stay unchanged
• src/splunk_ao/README_API_CLIENT.md references — tracked as follow-up

Pending (requires team input before workflows can run in CI)

• Bot git identity — email + username for automated commits in both workflows
• Splunk AO backend API URL — needed by regenerate-api-client.yaml
• Secrets provisioned — SPLUNK_AO_AUTOMATION_GITHUB_TOKEN, SPLUNK_AO_AUTOMATION_SSH_PRIVATE_KEY, DOCS_REPO

Test plan

• HYBIM-717 merged — src/splunk_ao exists on main
• Ran python3 scripts/create_docs.py — 73 .mdx files generated cleanly from src/splunk_ao/
• autogenerated header present in all output files
• pytest — 1813 passed, 134 skipped; 2 pre-existing optional-dep errors unrelated to this PR

[fercor-cisco]

🤖 This review was generated by the Astra agent. It may contain mistakes.

Verdict: request_changes — The added package_name key is not a recognized openapi-python-client config field and has no effect under --meta none; the path renames are otherwise correct.

[fercor-cisco]

🤖 This review was generated by the Astra agent. It may contain mistakes.

Verdict: needs_discussion — The OUTPUT_PATH rename targets src/splunk_ao/resources, which doesn't exist while the whole SDK still imports from galileo.resources, leaving the regen script in a broken/inconsistent state.

General Comments

• 🟡 minor (documentation): The PR description lists many changes (two new GitHub Actions workflows publish-docs.yaml / regenerate-api-client.yaml, edits to pydoc-markdown.yml, scripts/create_docs.py, openapi-client-config.yaml) that are not present in this branch's diff against origin/main — the actual change is 2 lines across 2 files. The workflow files do not exist in .github/workflows/. Please reconcile the description with the actual scope so reviewers and future readers aren't misled about what this PR ships.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• src/splunk_ao/README_API_CLIENT.md:1-39: This README still refers to "Galileo API client" / GalileoApiClient and uses from galileo.resources... example imports. Once the galileo→splunk_ao rename is complete, update these references for consistency with the new namespace.

[fercor-cisco]

I'll run another automated review.

[fercor-cisco]

🤖 This review was generated by the Astra agent. It may contain mistakes.

Verdict: request_changes — Two new workflows contain structural bugs that will fail or misbehave even after the pending secrets/identity TODOs are resolved: a read-only token that cannot push, a deprecated set-output command, and an ungated workflow_run trigger.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• .github/workflows/regenerate-api-client.yaml:75-75: git push --force ... --no-verify to a date-based branch will silently overwrite any prior same-day run's branch (and any manual edits to an existing open PR for that day). Consider using --force-with-lease or including ${{ github.run_id }} in the branch name (as publish-docs.yaml already does) to avoid clobbering.
• .github/workflows/publish-docs.yaml:60-64: The Update SDK docs step does rm -rf .../sdk-api/python/reference then cp -r ... .generated_docs/reference .../sdk-api/python/. If sdk-api/python/ does not yet exist in the docs repo, the cp will create a file named python rather than the intended directory tree. Consider mkdir -p on the target parent first to be robust.
• .github/workflows/publish-docs.yaml:1-13: Neither new workflow declares a concurrency group. Overlapping runs (e.g. a manual dispatch during a scheduled/workflow_run trigger) could race on branch creation/push. Adding a concurrency: block keyed on the workflow + ref would prevent overlapping publish/regenerate runs.

[fercor-cisco]

Running an automated review agent.

[etserend]

Workflow created PR against agent-observability-docs

[fercor-cisco]

🤖 This review was generated by the Astra agent. It may contain mistakes.

Verdict: request_changes — Both new workflows will fail their git commit step when there are no changes, causing recurring red runs (especially the daily cron); the doc-script example handling has a prose regression.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• .github/workflows/regenerate-api-client.yaml:58-70: BRANCH_NAME is derived only from the date (...update-api-client-<YYYY-MM-DD>). Re-running the workflow on the same day (manual workflow_dispatch or a retry) force-pushes the same branch; if a PR for that branch already exists, the final gh pr create step will fail. Consider appending ${{ github.run_id }} to the branch name, or making PR creation idempotent (check for an existing open PR before creating).
• scripts/create_docs.py:504-555: The new _escape_curly_braces, _convert_rst_code_blocks, and _sanitize_description helpers have no unit tests, and there are no tests for create_docs.py at all. These functions have non-trivial edge cases (nested fences, RST :: blocks with mixed indentation, curly braces adjacent to inline code). Adding focused unit tests would protect against regressions in the MDX-escaping logic.

[etserend]

All feedback addressed:

• No-op commit failures — both workflows now guard on git diff --cached --quiet; Create PR skipped when nothing changed
• Same-day branch collision — regen branch now includes ${{ github.run_id }}; || true removed
• Prose-only fencing — all description-only examples in this codebase are code; fencing is correct; noted as edge case to watch
• Unit tests for MDX helpers — agreed, tracked as follow-up

All previously flagged bugs fixed in earlier commits. Pipeline validated end-to-end.

[fercor-cisco]

Starting another automated review.

[fercor-cisco]

🤖 This review was generated by the Astra agent. It may contain mistakes.

Verdict: request_changes — Doc-gen regression: prose-only examples are now wrapped in a ```python fence (unaddressed reviewer comment); pending operational TODOs are tracked.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• .github/workflows/publish-docs.yaml:106-107: The Create PR step injects the static PR_BODY via ${{ env.PR_BODY }} into the shell command. It is a workflow-defined literal so there is no injection risk today, but referencing the shell variable directly (gh pr create --title "Updated Python SDK docs" --body "$PR_BODY") is more robust against future edits that add shell-special characters to the body.
• .github/workflows/regenerate-api-client.yaml:167-169: Bot git identity (email/name) and the SPLUNK_AO_API_URL secret are still TODO placeholders, and the same git-identity TODO exists in publish-docs.yaml. These are acknowledged in the PR description and tracked under HYBIM-725; surfacing here only so the workflows are not enabled in CI before the team provisions them.

[adityamehra]

@etserend Let's create a FAST ticket for the service account. Even though the team doesn't think service account is the correct approach but I feel like a ticket would help.

Other than this LGTM! Not sure, if some of the issues pointed out in the code review are related to new changes in your PR or were already in the legacy pipelines.

But would defer to Fernando's review.

[etserend]

Resolved all outstanding review items:

• Removed service account TODO placeholders; switched git identity to github-actions[bot]
• Added mkdir -p before cp in the docs copy step
• Fixed ${{ env.PR_BODY }} → "$PR_BODY" shell reference
• Fixed prose-only docstring examples being incorrectly wrapped in ```python fences — had_snippet flag now distinguishes real code from description-only examples at both emission sites

Unit tests for the MDX helpers remain tracked as a follow-up (acknowledged in earlier comment).

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: request_changes — Two concrete workflow bugs undermine the auto-generation pipeline this PR wires up: an unquoted pip version constraint and a workflow_run trigger pointing at a workflow that doesn't exist.

General Comments

• 🟡 minor (testing): scripts/create_docs.py gains non-trivial new logic (_convert_rst_code_blocks, _escape_curly_braces, _sanitize_description, and the rewritten example-emission branches keyed on had_snippet), but there are no unit tests covering any of it. The author acknowledged this as a tracked follow-up, so it is non-blocking, but the example-fencing branches in particular (>>> stripping via code[4:], prose-vs-code detection) are exactly the kind of string logic that regresses silently. Consider adding a few table-driven tests before this becomes load-bearing for published docs.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• .github/workflows/regenerate-api-client.yaml:62-62: git push --force is unnecessary here: BRANCH_NAME already embeds ${{ github.run_id }}, so every run targets a fresh branch that cannot pre-exist. A plain git push origin $BRANCH_NAME avoids the surprise of a force-push in automation and fails loudly if the uniqueness assumption is ever violated.
• .github/workflows/regenerate-api-client.yaml:54-54: ${{ secrets.SPLUNK_AO_API_URL }} is interpolated unquoted into the shell. If the secret is empty the underlying import-openapi-yaml.sh prints usage and exits 1 (acceptable), but consider passing it via an env var and quoting ("$API_URL") to guard against whitespace/special characters and to keep the value out of the rendered command line.

[fercor-cisco]

🟠 major (bug): This argument is unquoted, so bash parses >=0.17.0 as an output redirection: the command runs pip install docstring-parser (unpinned, latest) and writes stdout to a stray file literally named =0.17.0 in the workspace. The >=0.17.0 version floor is silently dropped and never enforced. Quote the requirement so pip receives it as a single argument.

Suggested change

	run: pip install docstring-parser>=0.17.0
	run: pip install 'docstring-parser>=0.17.0'

🤖 Generated by Astra

[fercor-cisco]

🟠 major (bug): The workflow_run trigger keys off a workflow named "Package Release", but no workflow with that name exists in .github/workflows/ (the names present are: CI - Test, Update API Client, Publish Docs, CLA Assistant, Test splunk-ao-a2a, Test splunk-ao-adk). GitHub matches workflow_run.workflows by the name: field, so this trigger will never fire — the only working entry point is manual workflow_dispatch, contradicting the PR's stated "triggers on release" behavior. Either add/rename the release workflow to "Package Release", or point this at the actual workflow name. If the release workflow lands in a separate PR, please confirm the sequencing.

🤖 Generated by Astra

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: approve — All prior review findings are resolved in the current HEAD; remaining items are minor/edge-case quality concerns and an acknowledged test follow-up.

General Comments

• 🟡 minor (design): The PR title/description states this "wires" doc auto-generation, but the release trigger in publish-docs.yaml is commented out (only workflow_dispatch is active) because the "Package Release" workflow doesn't exist yet. So publishing is manual-only for now. This appears intentional (matches the "Pending" section), but worth confirming that shipping the publish pipeline in a manual-only state is the desired end state for this PR rather than blocking on the release workflow landing first.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• scripts/create_docs.py:507-557: Add focused unit tests for the MDX helpers (_escape_curly_braces, _convert_rst_code_blocks, _sanitize_description) and the example-emission branches (fenced vs. doctest vs. prose-only/had_snippet). These string transforms have many branches that can regress silently; the author already acknowledged this as a tracked follow-up.
• .github/workflows/publish-docs.yaml:6-9: Once a "Package Release" workflow exists, uncomment/wire the workflow_run trigger (with the github.event.workflow_run.conclusion == 'success' guard previously discussed) so docs publish automatically on release rather than only via manual dispatch.

[fercor-cisco]

🟡 minor (bug): _convert_rst_code_blocks treats any description line ending in :: as the start of an RST literal block. This has two edge-case issues: (1) if a line ends in :: but no indented block follows (i.e. :: is incidental prose), the colons are silently stripped from the output text, altering the rendered prose; and (2) RST semantics render a trailing text:: as text: (one colon retained), whereas this strips both. Since there are no unit tests guarding this helper, consider only stripping/fencing when an indented block actually follows, and preserving a single colon for the text:: form.

🤖 Generated by Astra

[fercor-cisco]

🟡 minor (bug): If the SPLUNK_AO_API_URL secret is unset/empty, $API_URL expands to an empty string and import-openapi-yaml.sh prints usage and exits 1, failing the daily cron. That's a loud failure (acceptable), but note import-openapi-yaml.sh has no set -e and uses curl -s without --fail, so a non-empty-but-unreachable URL would write an empty openapi.yaml and continue silently rather than failing. Worth confirming the URL is validated / curl uses --fail before this cron runs in production.

🤖 Generated by Astra

[fercor-cisco]

Approved. Please see the follow-up suggestions above.