Skip to content

Commit 1d12358

Browse files
speedstorm1copybara-github
authored andcommitted
docs: publish the API reference on each release
PiperOrigin-RevId: 1002105602
1 parent 364889a commit 1d12358

37 files changed

Lines changed: 136 additions & 71441 deletions

‎.github/workflows/docs.yml‎

Lines changed: 136 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
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.
89
name: 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
1015
on:
16+
release:
17+
types: [published]
1118
workflow_dispatch:
1219
inputs:
1320
ref:
@@ -23,7 +30,27 @@ permissions:
2330
contents: read
2431

2532
jobs:
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

‎docs/.nojekyll‎

Whitespace-only changes.

‎docs/_sources/genai.rst.txt‎

Lines changed: 0 additions & 108 deletions
This file was deleted.

0 commit comments

Comments
 (0)