feat(docs): wire splunk-ao SDK reference doc auto-generation (HYBIM-725) #9
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Publishes SDK docs to the Splunk AO docs repo. | |
| name: Publish Docs | |
| on: | |
| workflow_dispatch: | |
| pull_request: | |
| types: [opened, synchronize] | |
| 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: | |
| - 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 | |
| uses: actions/checkout@v5 | |
| with: | |
| repository: splunk/agent-observability-docs | |
| path: ./splunk-ao-docs | |
| token: ${{ secrets.PAT_AO_DOC_AUTOMATION }} | |
| - name: Create a branch | |
| working-directory: ./splunk-ao-docs | |
| run: git checkout -b feat/update-docs-${GITHUB_REF_NAME}-${{ github.run_id }} | |
| - name: Update SDK docs | |
| 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 | |
| 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 }} | |
| - name: Create PR | |
| working-directory: ./splunk-ao-docs | |
| env: | |
| GH_TOKEN: ${{ secrets.PAT_AO_DOC_AUTOMATION }} | |
| 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 }}" |