Skip to content

Commit 8c15278

Browse files
dbenndbenn
authored
Merge pull request #582 from AAVSO/578-update-javadoc-for-vstar-from-latest-development-snapshot-release-via-an-action
578 update javadoc for vstar from latest development snapshot release via an action
2 parents 94b7b82 + 40d7406 commit 8c15278

6 files changed

Lines changed: 278 additions & 10 deletions

File tree

‎.github/workflows/checkerframework.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,8 @@ jobs:
8989
steps.cf-warnings.outputs.found == 'true'
9090
run: |
9191
DATE=$(date -u +%Y-%m-%d)
92-
cat > _site/data/checker.json <<DATAJSON
92+
mkdir -p _site/health/data
93+
cat > _site/health/data/checker.json <<DATAJSON
9394
{
9495
"updated": "${DATE}",
9596
"total": ${{ steps.cf-warnings.outputs.total }},

‎.github/workflows/javadoc.yml‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
# Build VStar Javadoc and publish it to the gh-pages branch under
2+
# javadoc/vstar/snapshot/ -- from the snapshot release tag
3+
# javadoc/vstar/release/ -- from the latest semantic-version tag
4+
#
5+
# Triggers:
6+
# - Any GitHub release publish (snapshot daily release or stable X.Y.Z release)
7+
# - Manual dispatch (with optional choice of which set to refresh)
8+
#
9+
# See: https://github.com/AAVSO/VStar/issues/578
10+
11+
name: Javadoc
12+
13+
on:
14+
release:
15+
types: [published]
16+
workflow_dispatch:
17+
inputs:
18+
target:
19+
description: 'Which Javadoc set(s) to refresh'
20+
required: true
21+
default: 'both'
22+
type: choice
23+
options:
24+
- both
25+
- snapshot
26+
- release
27+
28+
permissions:
29+
contents: write
30+
31+
jobs:
32+
javadoc:
33+
runs-on: ubuntu-latest
34+
timeout-minutes: 20
35+
name: Build & publish Javadoc
36+
37+
steps:
38+
- name: Decide which targets to build
39+
id: targets
40+
run: |
41+
# release event always rebuilds both (cheap and keeps the dashboard
42+
# consistent regardless of which kind of release fired the workflow)
43+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
44+
T="${{ inputs.target }}"
45+
else
46+
T="both"
47+
fi
48+
case "$T" in
49+
snapshot) BUILD_SNAPSHOT=true; BUILD_RELEASE=false ;;
50+
release) BUILD_SNAPSHOT=false; BUILD_RELEASE=true ;;
51+
both|*) BUILD_SNAPSHOT=true; BUILD_RELEASE=true ;;
52+
esac
53+
echo "build_snapshot=$BUILD_SNAPSHOT" >> "$GITHUB_OUTPUT"
54+
echo "build_release=$BUILD_RELEASE" >> "$GITHUB_OUTPUT"
55+
echo "Targets: snapshot=$BUILD_SNAPSHOT release=$BUILD_RELEASE"
56+
57+
- name: Set up Java
58+
uses: actions/setup-java@v4
59+
with:
60+
java-version: '17'
61+
distribution: 'temurin'
62+
63+
- name: Create plugin dirs
64+
run: |
65+
mkdir -p ~/vstar_plugins
66+
mkdir -p ~/vstar_plugin_libs
67+
68+
- name: Resolve snapshot ref
69+
id: snapref
70+
if: steps.targets.outputs.build_snapshot == 'true'
71+
run: |
72+
# Prefer the dedicated 'snapshot' tag (moved by daily-release.yml);
73+
# fall back to master if the tag is missing for any reason.
74+
if git ls-remote --tags https://github.com/${{ github.repository }}.git refs/tags/snapshot | grep -q .; then
75+
echo "ref=refs/tags/snapshot" >> "$GITHUB_OUTPUT"
76+
else
77+
echo "ref=refs/heads/master" >> "$GITHUB_OUTPUT"
78+
fi
79+
80+
- name: Resolve latest stable release tag
81+
id: relref
82+
if: steps.targets.outputs.build_release == 'true'
83+
run: |
84+
TAG=$(git ls-remote --tags https://github.com/${{ github.repository }}.git \
85+
| awk '{print $2}' \
86+
| sed 's|refs/tags/||;s|\^{}||' \
87+
| grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' \
88+
| sort -V \
89+
| tail -1)
90+
if [ -z "$TAG" ]; then
91+
echo "No semantic-version tag found; skipping release Javadoc."
92+
echo "found=false" >> "$GITHUB_OUTPUT"
93+
else
94+
echo "Latest stable release tag: $TAG"
95+
echo "found=true" >> "$GITHUB_OUTPUT"
96+
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
97+
fi
98+
99+
# ---------- Snapshot ----------
100+
- name: Checkout snapshot source
101+
if: steps.targets.outputs.build_snapshot == 'true'
102+
uses: actions/checkout@v4
103+
with:
104+
ref: ${{ steps.snapref.outputs.ref }}
105+
path: src_snapshot
106+
107+
- name: Build snapshot Javadoc
108+
if: steps.targets.outputs.build_snapshot == 'true'
109+
working-directory: src_snapshot
110+
# NB: name 'antlr4' explicitly so this works against historical checkouts
111+
# whose build.xml predates the javadoc->antlr4 dependency fix.
112+
run: ant -noinput -buildfile build.xml antlr4 javadoc
113+
114+
- name: Capture snapshot metadata
115+
if: steps.targets.outputs.build_snapshot == 'true'
116+
id: snapmeta
117+
working-directory: src_snapshot
118+
run: |
119+
SHA=$(git rev-parse HEAD)
120+
SHORT=$(git rev-parse --short=8 HEAD)
121+
CDATE=$(git log -1 --format=%cI HEAD | cut -dT -f1)
122+
echo "sha=$SHA" >> "$GITHUB_OUTPUT"
123+
echo "short=$SHORT" >> "$GITHUB_OUTPUT"
124+
echo "cdate=$CDATE" >> "$GITHUB_OUTPUT"
125+
126+
# ---------- Release ----------
127+
- name: Checkout release source
128+
if: steps.targets.outputs.build_release == 'true' && steps.relref.outputs.found == 'true'
129+
uses: actions/checkout@v4
130+
with:
131+
ref: refs/tags/${{ steps.relref.outputs.tag }}
132+
path: src_release
133+
134+
- name: Build release Javadoc
135+
if: steps.targets.outputs.build_release == 'true' && steps.relref.outputs.found == 'true'
136+
working-directory: src_release
137+
# NB: name 'antlr4' explicitly so this works against historical checkouts
138+
# whose build.xml predates the javadoc->antlr4 dependency fix.
139+
run: ant -noinput -buildfile build.xml antlr4 javadoc
140+
141+
- name: Capture release metadata
142+
if: steps.targets.outputs.build_release == 'true' && steps.relref.outputs.found == 'true'
143+
id: relmeta
144+
working-directory: src_release
145+
run: |
146+
SHA=$(git rev-parse HEAD)
147+
SHORT=$(git rev-parse --short=8 HEAD)
148+
CDATE=$(git log -1 --format=%cI HEAD | cut -dT -f1)
149+
echo "sha=$SHA" >> "$GITHUB_OUTPUT"
150+
echo "short=$SHORT" >> "$GITHUB_OUTPUT"
151+
echo "cdate=$CDATE" >> "$GITHUB_OUTPUT"
152+
153+
# ---------- Publish to gh-pages ----------
154+
- name: Checkout gh-pages
155+
uses: actions/checkout@v4
156+
with:
157+
ref: gh-pages
158+
path: _site
159+
160+
- name: Stage Javadoc into gh-pages worktree
161+
run: |
162+
DATE=$(date -u +%Y-%m-%d)
163+
mkdir -p _site/javadoc/vstar _site/javadoc/data
164+
165+
if [ "${{ steps.targets.outputs.build_snapshot }}" = "true" ] && \
166+
[ -d src_snapshot/doc/vstar_docs ]; then
167+
rm -rf _site/javadoc/vstar/snapshot
168+
mkdir -p _site/javadoc/vstar/snapshot
169+
cp -R src_snapshot/doc/vstar_docs/. _site/javadoc/vstar/snapshot/
170+
fi
171+
172+
if [ "${{ steps.targets.outputs.build_release }}" = "true" ] && \
173+
[ "${{ steps.relref.outputs.found }}" = "true" ] && \
174+
[ -d src_release/doc/vstar_docs ]; then
175+
rm -rf _site/javadoc/vstar/release
176+
mkdir -p _site/javadoc/vstar/release
177+
cp -R src_release/doc/vstar_docs/. _site/javadoc/vstar/release/
178+
fi
179+
180+
# Merge new metadata with whatever existing data/javadoc.json had,
181+
# so a snapshot-only or release-only run doesn't clobber the other set.
182+
python3 - "$DATE" \
183+
"${{ steps.targets.outputs.build_snapshot }}" \
184+
"${{ steps.snapmeta.outputs.sha }}" \
185+
"${{ steps.snapmeta.outputs.short }}" \
186+
"${{ steps.snapmeta.outputs.cdate }}" \
187+
"${{ steps.targets.outputs.build_release }}" \
188+
"${{ steps.relref.outputs.found }}" \
189+
"${{ steps.relref.outputs.tag }}" \
190+
"${{ steps.relmeta.outputs.sha }}" \
191+
"${{ steps.relmeta.outputs.short }}" \
192+
"${{ steps.relmeta.outputs.cdate }}" <<'PY'
193+
import json, os, sys
194+
date, do_snap, s_sha, s_short, s_cdate, do_rel, rel_found, r_tag, r_sha, r_short, r_cdate = sys.argv[1:]
195+
path = "_site/javadoc/data/javadoc.json"
196+
try:
197+
with open(path) as f:
198+
data = json.load(f)
199+
except (OSError, ValueError):
200+
data = {}
201+
data["updated"] = date
202+
if do_snap == "true":
203+
data["snapshot"] = {
204+
"commit": s_sha, "commit_short": s_short,
205+
"commit_date": s_cdate, "generated": date,
206+
"path": "vstar/snapshot/",
207+
}
208+
if do_rel == "true" and rel_found == "true":
209+
data["release"] = {
210+
"tag": r_tag, "commit": r_sha, "commit_short": r_short,
211+
"commit_date": r_cdate, "generated": date,
212+
"path": "vstar/release/",
213+
}
214+
with open(path, "w") as f:
215+
json.dump(data, f, indent=2)
216+
f.write("\n")
217+
print(json.dumps(data, indent=2))
218+
PY
219+
220+
- name: Commit and push to gh-pages
221+
working-directory: _site
222+
run: |
223+
DATE=$(date -u +%Y-%m-%d)
224+
git config user.email "github-actions[bot]@users.noreply.github.com"
225+
git config user.name "github-actions[bot]"
226+
git add -A
227+
if git diff --cached --quiet; then
228+
echo "No Javadoc changes to publish."
229+
exit 0
230+
fi
231+
SUMMARY="Update Javadoc"
232+
if [ "${{ steps.targets.outputs.build_snapshot }}" = "true" ] && [ "${{ steps.targets.outputs.build_release }}" = "true" ]; then
233+
SUMMARY="Update Javadoc (snapshot ${{ steps.snapmeta.outputs.short }} + release ${{ steps.relref.outputs.tag }})"
234+
elif [ "${{ steps.targets.outputs.build_snapshot }}" = "true" ]; then
235+
SUMMARY="Update snapshot Javadoc (${{ steps.snapmeta.outputs.short }})"
236+
elif [ "${{ steps.targets.outputs.build_release }}" = "true" ]; then
237+
SUMMARY="Update release Javadoc (${{ steps.relref.outputs.tag }})"
238+
fi
239+
git commit -m "${SUMMARY} [${DATE}]"
240+
for i in 1 2 3; do
241+
git pull --rebase origin gh-pages && git push origin gh-pages && break
242+
echo "Push attempt $i failed, retrying in $((i * 5))s..."
243+
sleep $((i * 5))
244+
done
245+
246+
- name: Step summary
247+
if: always()
248+
run: |
249+
cat >> "$GITHUB_STEP_SUMMARY" <<EOF
250+
## Javadoc publication
251+
252+
| Set | Built | Source |
253+
|-----|-------|--------|
254+
| snapshot | ${{ steps.targets.outputs.build_snapshot }} | ${{ steps.snapmeta.outputs.short }} (${{ steps.snapmeta.outputs.cdate }}) |
255+
| release | ${{ steps.targets.outputs.build_release }} (${{ steps.relref.outputs.found }}) | ${{ steps.relref.outputs.tag }} @ ${{ steps.relmeta.outputs.short }} (${{ steps.relmeta.outputs.cdate }}) |
256+
257+
Published to: https://aavso.github.io/VStar/javadoc/
258+
EOF

‎.github/workflows/plugin-UT.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,8 @@ jobs:
191191
steps.metrics.outputs.tests != '0'
192192
run: |
193193
DATE=$(date -u +%Y-%m-%d)
194-
cat > _site/data/plugin-coverage.json <<DATAJSON
194+
mkdir -p _site/health/data _site/health/coverage/plugins
195+
cat > _site/health/data/plugin-coverage.json <<DATAJSON
195196
{
196197
"updated": "${DATE}",
197198
"java_version": "17",
@@ -204,9 +205,9 @@ jobs:
204205
}
205206
DATAJSON
206207
207-
rm -rf _site/coverage/plugins/*
208+
rm -rf _site/health/coverage/plugins/*
208209
if [ -d "plugin/test_report/coverage" ]; then
209-
cp -r plugin/test_report/coverage/* _site/coverage/plugins/
210+
cp -r plugin/test_report/coverage/* _site/health/coverage/plugins/
210211
fi
211212
212213
cd _site

‎.github/workflows/spotbugs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,8 @@ jobs:
9898
steps.sb-counts.outputs.found == 'true'
9999
run: |
100100
DATE=$(date -u +%Y-%m-%d)
101-
cat > _site/data/spotbugs.json <<DATAJSON
101+
mkdir -p _site/health/data
102+
cat > _site/health/data/spotbugs.json <<DATAJSON
102103
{
103104
"updated": "${DATE}",
104105
"total": ${{ steps.sb-counts.outputs.total }},

‎.github/workflows/vstar-UT.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -188,7 +188,8 @@ jobs:
188188
steps.metrics.outputs.tests != '0'
189189
run: |
190190
DATE=$(date -u +%Y-%m-%d)
191-
cat > _site/data/coverage.json <<DATAJSON
191+
mkdir -p _site/health/data _site/health/coverage/vstar
192+
cat > _site/health/data/coverage.json <<DATAJSON
192193
{
193194
"updated": "${DATE}",
194195
"java_version": "17",
@@ -201,9 +202,9 @@ jobs:
201202
}
202203
DATAJSON
203204
204-
rm -rf _site/coverage/vstar/*
205+
rm -rf _site/health/coverage/vstar/*
205206
if [ -d "test_report/coverage" ]; then
206-
cp -r test_report/coverage/* _site/coverage/vstar/
207+
cp -r test_report/coverage/* _site/health/coverage/vstar/
207208
fi
208209
209210
cd _site

‎build.xml‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -596,12 +596,18 @@
596596

597597
<!-- Documentation targets -->
598598

599-
<target name="javadoc" description="Javadoc generation">
599+
<target name="javadoc" depends="init,antlr4" description="Javadoc generation">
600600
<delete failonerror="false" includeemptydirs="true">
601601
<fileset dir="${javadoc}" includes="**/*" />
602602
</delete>
603603

604-
<javadoc sourcepath="${src}" destdir="${javadoc}" classpathref="build.classpath" header="VStar" />
604+
<!-- Lift the default 100/100 caps so the build reports true error/warning totals. -->
605+
<javadoc sourcepath="${src}" destdir="${javadoc}" classpathref="build.classpath" header="VStar">
606+
<arg value="-Xmaxerrs" />
607+
<arg value="9999" />
608+
<arg value="-Xmaxwarns" />
609+
<arg value="9999" />
610+
</javadoc>
605611

606612
<zip destfile="${doc}/vstar_docs.zip" basedir="${doc}" includes="vstar_docs/**/*" />
607613
</target>

0 commit comments

Comments
 (0)