From 3e5d38433fa6f3584074bf597c03257aca54778d Mon Sep 17 00:00:00 2001 From: Sankalp-Mittal Date: Thu, 17 Sep 2026 10:06:59 +0000 Subject: [PATCH 1/6] Auto-publish PyDABs reference docs to gh-pages on release Add an update-pydabs-docs workflow that rebuilds the PyDABs Python reference docs and publishes the HTML to the gh-pages branch on each release tag (and via workflow_dispatch), replacing the manual copy. Modeled on update-schema-docs.yml: same runner group, JFrog/Go/uv setup, and gh-pages worktree + github-actions[bot] commit + direct push pattern. Co-authored-by: Isaac --- .github/workflows/update-pydabs-docs.yml | 103 +++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 .github/workflows/update-pydabs-docs.yml diff --git a/.github/workflows/update-pydabs-docs.yml b/.github/workflows/update-pydabs-docs.yml new file mode 100644 index 00000000000..25324a3337f --- /dev/null +++ b/.github/workflows/update-pydabs-docs.yml @@ -0,0 +1,103 @@ +name: update-pydabs-docs + +# Rebuild the PyDABs Python reference docs after every release and publish the +# HTML to the `gh-pages` branch (served at https://databricks.github.io/cli/python/). +# The docs are NOT kept on main — `gh-pages` is their published home, and until +# now it was refreshed by hand. The generated `.rst` pages live on main; this +# workflow just runs the Sphinx build and copies the output onto `gh-pages`. + +on: + push: + tags: + - "v[0-9]+.[0-9]+.[0-9]+*" + + workflow_dispatch: + +permissions: + contents: write + # Required by setup-jfrog (GOPROXY exchange). + id-token: write + +jobs: + update-pydabs-docs: + runs-on: + group: databricks-protected-runner-group-large + labels: linux-ubuntu-latest-large + + steps: + - name: Checkout main + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + # Build runs against `main`. fetch-tags lets the workflow_dispatch path + # below resolve the most recent release tag for the commit message. + ref: main + fetch-depth: 0 + fetch-tags: true + + - name: Setup JFrog + uses: ./.github/actions/setup-jfrog + + - name: Setup Go + uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: go.mod + + - name: Install uv + uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + with: + version: "0.6.5" + + - name: Determine release tag + id: tag + env: + REF_TYPE: ${{ github.ref_type }} + REF_NAME: ${{ github.ref_name }} + run: | + if [ "$REF_TYPE" = "tag" ]; then + tag="$REF_NAME" + else + # git tag --list uses fnmatch (no `+`), so post-filter with grep + # to match the same shape as the trigger above. + tag=$(git tag --list 'v*' --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' | head -n 1) + fi + if [ -z "$tag" ]; then + echo "Could not determine a release tag to publish for." >&2 + exit 1 + fi + echo "tag=$tag" >> "$GITHUB_OUTPUT" + echo "Publishing for tag $tag" + + - name: Check out gh-pages worktree + run: | + git fetch origin gh-pages + git worktree add "$RUNNER_TEMP/ghpages" origin/gh-pages + + - name: Build the PyDABs docs + run: go tool -modfile=tools/task/go.mod task pydabs-docs + + # gh-pages holds the Sphinx output under python/; replace it wholesale so a + # dropped resource loses its page. Only python/ is touched — the top-level + # .nojekyll, index.html, and experimental/ are left as-is. + - name: Copy built docs into the gh-pages worktree + run: | + rm -rf "$RUNNER_TEMP/ghpages/python" + mkdir -p "$RUNNER_TEMP/ghpages/python" + cp -R python/docs/_output/. "$RUNNER_TEMP/ghpages/python/" + + - name: Stage regenerated docs on gh-pages + working-directory: ${{ runner.temp }}/ghpages + run: git add -A python + + - name: Commit and push to gh-pages + working-directory: ${{ runner.temp }}/ghpages + env: + TAG: ${{ steps.tag.outputs.tag }} + run: |- + if git diff --cached --quiet; then + echo "gh-pages already up to date for ${TAG}; nothing to commit." + exit 0 + fi + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "Update PyDABs reference docs for ${TAG}" + git push origin HEAD:gh-pages From 74ea70b40826318388ac23b7c661795a408e985b Mon Sep 17 00:00:00 2001 From: Sankalp-Mittal Date: Thu, 17 Sep 2026 15:18:38 +0000 Subject: [PATCH 2/6] Fail the PyDABs docs build on RST breakage Add -W to the pydabs-docs sphinx-build command so warnings (e.g. malformed upstream descriptions or unresolved cross-references introduced by an SDK bump) fail the build instead of passing silently. This makes both the existing python_docs CI job and the new gh-pages publish workflow strict, surfacing docs breakage at bump time. Fix the one pre-existing warning this exposes: the Resources docstring referenced add_job with :meth:, but add_job is a generated method Sphinx cannot resolve. Use an inline literal instead. Co-authored-by: Isaac --- python/Taskfile.yml | 2 +- python/databricks/bundles/core/_resources.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/python/Taskfile.yml b/python/Taskfile.yml index fd4b18687be..34f34676b68 100644 --- a/python/Taskfile.yml +++ b/python/Taskfile.yml @@ -59,7 +59,7 @@ tasks: generates: - docs/_output/** cmds: - - "uv run --python 3.12 sphinx-build docs docs/_output --show-traceback --nitpicky --fresh-env --keep-going" + - "uv run --python 3.12 sphinx-build docs docs/_output --show-traceback --nitpicky --fresh-env --keep-going -W" pydabs-codegen: desc: Run pydabs codegen diff --git a/python/databricks/bundles/core/_resources.py b/python/databricks/bundles/core/_resources.py index 6818031596c..f4720d80299 100644 --- a/python/databricks/bundles/core/_resources.py +++ b/python/databricks/bundles/core/_resources.py @@ -33,7 +33,7 @@ class Resources(_GeneratedResources): - :meth:`load_resources_from_modules` - :meth:`load_resources_from_module` - Programmatic construction of resources is supported using :meth:`add_resource` and :meth:`add_job` methods. + Programmatic construction of resources is supported using :meth:`add_resource` and ``add_job`` methods. Example: From b2779c27c4880d16f0e0a9511267cd00921fc7b8 Mon Sep 17 00:00:00 2001 From: Sankalp-Mittal Date: Thu, 17 Sep 2026 15:31:50 +0000 Subject: [PATCH 3/6] Generalize the typed-adder reference in the Resources docstring Refer to the generated per-resource adders as ``add_`` rather than singling out add_job, which was only an example among add_cluster, add_app, etc. Co-authored-by: Isaac --- python/databricks/bundles/core/_resources.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/databricks/bundles/core/_resources.py b/python/databricks/bundles/core/_resources.py index f4720d80299..74f186c3714 100644 --- a/python/databricks/bundles/core/_resources.py +++ b/python/databricks/bundles/core/_resources.py @@ -33,7 +33,7 @@ class Resources(_GeneratedResources): - :meth:`load_resources_from_modules` - :meth:`load_resources_from_module` - Programmatic construction of resources is supported using :meth:`add_resource` and ``add_job`` methods. + Programmatic construction of resources is supported using :meth:`add_resource` and ``add_`` methods. Example: From d0aa866dcb8f3300e50f1efbd0d01273aed32437 Mon Sep 17 00:00:00 2001 From: Sankalp-Mittal Date: Mon, 21 Sep 2026 10:59:19 +0000 Subject: [PATCH 4/6] Rename the workflow to release-pydabs-docs Align with the release-* workflow family that runs post-release, and update the internal name: to match. Co-authored-by: Isaac --- .../{update-pydabs-docs.yml => release-pydabs-docs.yml} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename .github/workflows/{update-pydabs-docs.yml => release-pydabs-docs.yml} (99%) diff --git a/.github/workflows/update-pydabs-docs.yml b/.github/workflows/release-pydabs-docs.yml similarity index 99% rename from .github/workflows/update-pydabs-docs.yml rename to .github/workflows/release-pydabs-docs.yml index 25324a3337f..4c7ecb15a7f 100644 --- a/.github/workflows/update-pydabs-docs.yml +++ b/.github/workflows/release-pydabs-docs.yml @@ -1,4 +1,4 @@ -name: update-pydabs-docs +name: release-pydabs-docs # Rebuild the PyDABs Python reference docs after every release and publish the # HTML to the `gh-pages` branch (served at https://databricks.github.io/cli/python/). From 5a35a87b9f9528bd9b1c1625a6b654d84491222e Mon Sep 17 00:00:00 2001 From: Sankalp-Mittal Date: Mon, 21 Sep 2026 10:59:33 +0000 Subject: [PATCH 5/6] Use a standard runner for the docs workflow PyDABs doc generation is a lightweight Sphinx build, so the -large protected runner is overkill. Drop to the standard protected runner (matching tagging.yml, which is also tag-triggered and pushes to the repo). Co-authored-by: Isaac --- .github/workflows/release-pydabs-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release-pydabs-docs.yml b/.github/workflows/release-pydabs-docs.yml index 4c7ecb15a7f..c7d4ee4c7e4 100644 --- a/.github/workflows/release-pydabs-docs.yml +++ b/.github/workflows/release-pydabs-docs.yml @@ -21,8 +21,8 @@ permissions: jobs: update-pydabs-docs: runs-on: - group: databricks-protected-runner-group-large - labels: linux-ubuntu-latest-large + group: databricks-protected-runner-group + labels: linux-ubuntu-latest steps: - name: Checkout main From 4db1247cbd187ba9768a91e1cdac4ff2da20ecb0 Mon Sep 17 00:00:00 2001 From: Sankalp-Mittal Date: Mon, 21 Sep 2026 11:52:51 +0000 Subject: [PATCH 6/6] Drop fetch-depth: 0 from the docs workflow checkout Full history is not needed: the build reads only the current main tree, and the release-tag lookup uses tag refs (fetch-tags), not file content at historical tags. Full history was inherited from update-schema-docs, whose since_version.go reads `git show :...` per release. Co-authored-by: Isaac --- .github/workflows/release-pydabs-docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/release-pydabs-docs.yml b/.github/workflows/release-pydabs-docs.yml index c7d4ee4c7e4..7197c9f955a 100644 --- a/.github/workflows/release-pydabs-docs.yml +++ b/.github/workflows/release-pydabs-docs.yml @@ -31,7 +31,6 @@ jobs: # Build runs against `main`. fetch-tags lets the workflow_dispatch path # below resolve the most recent release tag for the commit message. ref: main - fetch-depth: 0 fetch-tags: true - name: Setup JFrog