11# Builds the API reference (https://googleapis.github.io/python-genai/) with the
2- # pinned Sphinx in docs/requirements.txt and publishes it to GitHub Pages.
2+ # pinned Sphinx in docs/requirements.txt and publishes it to GitHub Pages,
3+ # whenever a release is published. Each release also gets the built site as a
4+ # zip, and a failed publish opens a "Docs workflow failed" issue that the next
5+ # successful one closes.
36#
4- # Run by hand from the Actions tab for now, from main: the github-pages
5- # environment only accepts deployments from main. Publishing also needs the
6- # repository's Pages source set to "GitHub Actions"; until then, leave "deploy"
7- # unchecked to build the site and download it as an artifact.
7+ # Run it by hand from the Actions tab, from main, to rebuild a tag; leave
8+ # "deploy" unchecked to only build the site and download it as an artifact.
89name : Docs
10+ # Publishing runs are named "Docs <tag> (publish)"; release tooling finds the
11+ # run for a release by this name, so keep the format.
12+ run-name : >-
13+ Docs ${{ inputs.ref || github.event.release.tag_name }}${{ inputs.deploy && ' (publish)' || '' }}
914
1015on :
16+ release :
17+ types : [published]
1118 workflow_dispatch :
1219 inputs :
1320 ref :
@@ -23,7 +30,27 @@ permissions:
2330 contents : read
2431
2532jobs :
33+ # The github-pages environment only accepts deployments from main, and a
34+ # release run's ref is its tag. So a release starts a run of this workflow on
35+ # main that builds and publishes the tag.
36+ dispatch :
37+ if : >-
38+ github.event_name == 'release' && !github.event.release.prerelease &&
39+ github.repository == 'googleapis/python-genai'
40+ runs-on : ubuntu-latest
41+ permissions :
42+ actions : write
43+ steps :
44+ - name : Start a run on main for the release tag
45+ env :
46+ GH_TOKEN : ${{ github.token }}
47+ TAG : ${{ github.event.release.tag_name }}
48+ run : |
49+ gh workflow run docs.yml --repo "$GITHUB_REPOSITORY" --ref main \
50+ -f ref="$TAG" -f deploy=true
51+
2652 build :
53+ if : github.event_name == 'workflow_dispatch'
2754 runs-on : ubuntu-latest
2855 steps :
2956 - name : Checkout code
@@ -45,19 +72,57 @@ jobs:
4572 # The docs import `genai` from the checkout, as build_and_copy_docs.sh
4673 # does from its copy in docs/google. custom.css is copied in first, as
4774 # that script does. The doctree cache goes outside the site, so it is
48- # not published.
75+ # not published. `shell: bash` adds pipefail, so tee keeps
76+ # sphinx-build's exit code.
77+ shell : bash
4978 env :
5079 PYTHONPATH : ${{ github.workspace }}/google
5180 run : |
5281 mkdir -p _site/_static/css
5382 cp docs/source/custom.css _site/_static/css/custom.css
54- sphinx-build -b html -d "$RUNNER_TEMP/doctrees" docs/source _site
83+ sphinx-build -b html -d "$RUNNER_TEMP/doctrees" docs/source _site \
84+ 2>&1 | tee "$RUNNER_TEMP/sphinx.log"
85+
86+ - name : Check the site
87+ # Sphinx exits 0 when autodoc cannot import a module, leaving a page
88+ # without the API in it, and other Sphinx versions have dropped the
89+ # pydantic JSON schemas. A full build has a ~30 MB genai.html with
90+ # about 400 schemas.
91+ run : |
92+ python - "$RUNNER_TEMP/sphinx.log" <<'EOF'
93+ import pathlib, re, sys
94+ problems = []
95+ failed = re.findall(r"^.*autodoc: failed to import.*$",
96+ pathlib.Path(sys.argv[1]).read_text(), re.M)
97+ if failed:
98+ problems.append("autodoc could not import:\n " + "\n ".join(failed[:5]))
99+ genai = pathlib.Path("_site/genai.html")
100+ html = genai.read_text(errors="replace") if genai.exists() else ""
101+ if len(html) < 10_000_000:
102+ problems.append(f"genai.html is {len(html):,} characters, not ~30 MB")
103+ schemas = html.count("Show JSON schema")
104+ if schemas < 300:
105+ problems.append(f"genai.html has {schemas} JSON schemas, not ~400")
106+ if problems:
107+ sys.exit("The site looks broken; not publishing it.\n" + "\n".join(problems))
108+ print(f"genai.html: {len(html):,} characters, {schemas} JSON schemas")
109+ EOF
55110
56111 - name : Upload the site
57112 uses : actions/upload-pages-artifact@v3
58113 with :
59114 path : _site
60115
116+ - name : Zip the site
117+ run : cd _site && zip -qr "$RUNNER_TEMP/site.zip" .
118+
119+ - name : Upload the zip
120+ uses : actions/upload-artifact@v4
121+ with :
122+ name : site-zip
123+ path : ${{ runner.temp }}/site.zip
124+ retention-days : 1
125+
61126 deploy :
62127 if : inputs.deploy
63128 needs : build
@@ -76,3 +141,67 @@ jobs:
76141 - name : Publish to GitHub Pages
77142 id : deployment
78143 uses : actions/deploy-pages@v4
144+
145+ # Pages serves only the latest site, so each release keeps its own copy.
146+ archive :
147+ if : inputs.deploy
148+ needs : build
149+ runs-on : ubuntu-latest
150+ permissions :
151+ contents : write
152+ steps :
153+ - name : Download the zip
154+ uses : actions/download-artifact@v4
155+ with :
156+ name : site-zip
157+
158+ - name : Attach it to the release
159+ env :
160+ GH_TOKEN : ${{ github.token }}
161+ REF : ${{ inputs.ref }}
162+ run : |
163+ if ! gh release view "$REF" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
164+ echo "No release named $REF; the site is not attached anywhere."
165+ exit 0
166+ fi
167+ mv site.zip "python-genai-docs-$REF.zip"
168+ gh release upload "$REF" "python-genai-docs-$REF.zip" \
169+ --repo "$GITHUB_REPOSITORY" --clobber
170+
171+ # Nobody watches a release's run, so a failure opens an issue (or comments on
172+ # the open one), and the next successful publish closes it.
173+ report :
174+ if : >-
175+ always() && github.repository == 'googleapis/python-genai' &&
176+ (github.event_name == 'release' || inputs.deploy)
177+ needs : [dispatch, build, deploy, archive]
178+ runs-on : ubuntu-latest
179+ permissions :
180+ issues : write
181+ steps :
182+ - name : Open or close the failure issue
183+ env :
184+ GH_TOKEN : ${{ github.token }}
185+ FAILED : >-
186+ ${{ contains(needs.*.result, 'failure') ||
187+ contains(needs.*.result, 'cancelled') }}
188+ REF : ${{ inputs.ref || github.event.release.tag_name }}
189+ RUN : >-
190+ ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
191+ TITLE : Docs workflow failed
192+ run : |
193+ open=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open \
194+ --search "\"$TITLE\" in:title" --json number,title \
195+ --jq ".[] | select(.title == \"$TITLE\") | .number" | head -n 1)
196+ if [ "$FAILED" = true ]; then
197+ body="The API reference for $REF was not published. See $RUN"
198+ if [ -n "$open" ]; then
199+ gh issue comment "$open" --repo "$GITHUB_REPOSITORY" --body "$body"
200+ else
201+ gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body "$body"
202+ fi
203+ elif [ -n "$open" ] && [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then
204+ # A release run only starts the publishing run; that one closes it.
205+ gh issue close "$open" --repo "$GITHUB_REPOSITORY" \
206+ --comment "Published $REF. See $RUN"
207+ fi
0 commit comments