ci: add docs build as parallel CI job [PYSDK-110] (#600)

* ci: add docs build as parallel CI job [PYSDK-110]

Add _docs.yml reusable workflow running `make docs` on ubuntu-latest and
wire it into ci-cd.yml in parallel with lint/audit/test so the documentation
build is verified on every PR, not only at publish time.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(ci): document _docs.yml reusable workflow in .github/CLAUDE.md [PYSDK-110]

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: helmut-hoffer-von-ankershoffen

.github/CLAUDE.md

@@ -90,6 +90,7 @@ The Aignostics Python SDK uses a **sophisticated multi-stage CI/CD pipeline** bu
 | Workflow | Purpose | Duration | Key Outputs |
 |----------|---------|----------|-------------|
 | **_lint.yml** | Code quality (ruff, pyright, mypy) | ~5 min | Formatted code, type safety |
+| **_docs.yml** | Documentation build (Sphinx) | ~3 min | HTML docs, validation |
 | **_audit.yml** | Security + license compliance | ~3 min | SBOM (CycloneDX, SPDX), vulnerabilities, licenses |
 | **_test.yml** | Multi-stage test execution | ~15 min | Coverage reports, JUnit XML |
 | **_codeql.yml** | Security vulnerability scanning | ~10 min | CodeQL SARIF results |
@@ -1099,6 +1100,7 @@ make dist_native
 | `audit-scheduled.yml` | Entry | Security audit | ~5 min |
 | `codeql-scheduled.yml` | Entry | CodeQL scan | ~10 min |
 | `_lint.yml` | Reusable | Code quality checks | ~5 min |
+| `_docs.yml` | Reusable | Documentation build | ~3 min |
 | `_audit.yml` | Reusable | Security & license | ~3 min |
 | `_test.yml` | Reusable | Test execution | ~15 min |
 | `_codeql.yml` | Reusable | Security scanning | ~10 min |

.github/workflows/_docs.yml

@@ -0,0 +1,37 @@
+name: "> Docs"
+
+on:
+  workflow_call:
+    # No secrets needed
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      packages: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          version-file: "pyproject.toml"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install dev tools
+        shell: bash
+        run: .github/workflows/_install_dev_tools.bash
+
+      - name: Install Python, venv and dependencies
+        shell: bash
+        run: uv sync --all-extras --frozen --link-mode=copy
+
+      - name: Docs
+        shell: bash
+        run: make docs

.github/workflows/ci-cd.yml

@@ -77,6 +77,19 @@ jobs:
       id-token: write
       packages: read
 
+  docs:
+    needs: [get-commit-message]
+    if: |
+      (!contains(needs.get-commit-message.outputs.commit_message, 'skip:ci')) &&
+      (!contains(needs.get-commit-message.outputs.commit_message, 'build:native:only')) &&
+      (!contains(github.event.pull_request.labels.*.name, 'skip:ci')) &&
+      (!contains(github.event.pull_request.labels.*.name, 'build:native:only'))
+    uses: ./.github/workflows/_docs.yml
+    permissions:
+      contents: read
+      id-token: write
+      packages: read
+
   audit:
     needs: [get-commit-message]
     if: |
@@ -156,7 +169,7 @@ jobs:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
   ketryx_report_and_check:
-    needs: [get-commit-message, lint, audit, test, codeql, sonarcloud]
+    needs: [get-commit-message, lint, audit, test, codeql, sonarcloud, docs]
     if: |
       github.actor != 'dependabot[bot]' &&
       (!contains(needs.get-commit-message.outputs.commit_message, 'skip:ci')) &&