Skip to content

Commit 48718d6

Browse files
c-dilksc-dilks
authored
feat: generate and deploy javadoc documentation (JeffersonLab#257)
* feat: generate `javadoc` documentation * ci: re-trigger * fix: `needs` * fix: runner name * fix: needs * fix: `set -e` * fix: maybe we do need the build targets * feat: generate front page * fix: use `bash` * fix: the script is `bash` too * fix: re-enable full workflow
1 parent 3633022 commit 48718d6

File tree

5 files changed

+102
-63
lines changed

5 files changed

+102
-63
lines changed

‎.github/workflows/maven.yml‎

Lines changed: 54 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ concurrency:
1616
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
1717
cancel-in-progress: true
1818

19+
defaults:
20+
run:
21+
shell: bash
22+
1923
env:
2024
java_version: 11
2125
java_distribution: zulu
@@ -33,8 +37,6 @@ jobs:
3337
runner:
3438
- ubuntu-latest
3539
- macos-latest
36-
outputs:
37-
default_runner: ubuntu-latest
3840
runs-on: ${{ matrix.runner }}
3941
steps:
4042
- uses: actions/checkout@v4
@@ -57,8 +59,9 @@ jobs:
5759
run: validation/jacoco-aggregate.sh
5860
- name: publish jacoco report
5961
if: ${{ matrix.runner == 'ubuntu-latest' }}
60-
uses: actions/upload-pages-artifact@v3
62+
uses: actions/upload-artifact@v4
6163
with:
64+
name: jacoco_report
6265
path: publish/
6366
retention-days: 1
6467

@@ -110,7 +113,7 @@ jobs:
110113
111114
test_run-groovy:
112115
needs: [ build ]
113-
runs-on: ${{ needs.build.outputs.default_runner }}
116+
runs-on: ubuntu-latest
114117
steps:
115118
- uses: actions/checkout@v4
116119
- name: Set up JDK
@@ -124,7 +127,7 @@ jobs:
124127
groovy-version: ${{ env.groovy_version }}
125128
- uses: actions/download-artifact@v4
126129
with:
127-
name: build_${{ needs.build.outputs.default_runner }}
130+
name: build_ubuntu-latest
128131
- name: untar build
129132
run: tar xzvf coatjava.tar.gz
130133
- name: test run-groovy
@@ -135,17 +138,60 @@ jobs:
135138
- build
136139
- test_coatjava
137140
- test_run-groovy
138-
runs-on: ${{ needs.build.outputs.default_runner }}
141+
runs-on: ubuntu-latest
139142
steps:
140143
- name: pass
141144
run: exit 0
142145

146+
# generate documentation
147+
#############################################################################
148+
149+
generate_documentation:
150+
runs-on: ubuntu-latest
151+
steps:
152+
- uses: actions/checkout@v4
153+
- name: Set up JDK
154+
uses: actions/setup-java@v4
155+
with:
156+
java-version: ${{ env.java_version }}
157+
distribution: ${{ env.java_distribution }}
158+
- name: build
159+
run: ./build-coatjava.sh
160+
- name: generate documentation
161+
run: ./build-javadocs.sh
162+
- uses: actions/upload-artifact@v4
163+
with:
164+
name: javadoc
165+
path: docs/javadoc/
166+
retention-days: 1
167+
143168
# deploy web pages
144169
#############################################################################
145170

171+
collect_webpages:
172+
if: ${{ github.head_ref == 'development' || github.ref_name == 'development' }}
173+
needs: [ build, generate_documentation ]
174+
runs-on: ubuntu-latest
175+
steps:
176+
- name: download jacoco report
177+
uses: actions/download-artifact@v4
178+
with:
179+
name: jacoco_report
180+
path: pages/jacoco
181+
- name: download javadoc documentation
182+
uses: actions/download-artifact@v4
183+
with:
184+
name: javadoc
185+
path: pages/javadoc
186+
- run: tree pages
187+
- uses: actions/upload-pages-artifact@v3
188+
with:
189+
retention-days: 1
190+
path: pages/
191+
146192
deploy_web_pages:
147-
if: ${{ github.event_name == 'push' }}
148-
needs: build
193+
if: ${{ github.head_ref == 'development' || github.ref_name == 'development' }}
194+
needs: collect_webpages
149195
permissions:
150196
pages: write
151197
id-token: write

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
# COATJAVA
22
[![Build Status](https://github.com/jeffersonlab/coatjava/workflows/Coatjava-CI/badge.svg)](https://github.com/jeffersonlab/coatjava/actions)
33
[![Validation Status](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml/badge.svg)](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml)
4-
[![Coverage](https://badgen.net/static/JaCoCo/coverage/purple)](https://jeffersonlab.github.io/coatjava)
4+
[![Coverage](https://badgen.net/static/JaCoCo/coverage/purple)](https://jeffersonlab.github.io/coatjava/jacoco)
5+
6+
- [API Documentation (Javadoc)](https://jeffersonlab.github.io/coatjava/javadoc)
7+
8+
----
59

610
The original repository for COATJAVA was named "clas12-offline-software" and is [now archived and read-only](https://github.com/JeffersonLab/clas12-offline-software). On May 17, 2023, this new repository was created by running BFG Repo Cleaner to get rid of old, large data files and things that should never have been in the repository, giving 10x reduction in repository size, clone time, etc, and renamed `coatjava`. The most critical, GitHub-specific aspects have been transferred to this new repository:
711

@@ -27,8 +31,6 @@ For anything more, see the "General Developer Documentation" link on that softwa
2731

2832
The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wiki/Troubleshooting) wiki page may also still be useful but likely outdated.
2933

30-
<!--Javadocs can be found at the repository's [gh-page](https://jeffersonlab.github.io/clas12-offline-software/). A build history can be found at [Travis CI](https://travis-ci.org/JeffersonLab/clas12-offline-software).-->
31-
3234
<!--
3335
## Repository Structure and Dependency Management
3436
### Common Tools

‎build-javadocs.sh‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
1-
#!/bin/sh
1+
#!/bin/bash
22
#
33
# surely this should be done more properly with only maven, meanwhile ...
44
#
55

6-
mvn javadoc:javadoc -Ddoclint=none
6+
set -e
77

8+
##### generate documentation
9+
mvn javadoc:javadoc -Ddoclint=none
10+
11+
12+
##### collect documentation
813
src=target/site/apidocs
914
dest=docs/javadoc
1015

@@ -14,5 +19,39 @@ do
1419
cp -r $dir/* $dest/${dir%$src}
1520
done
1621

17-
#scp -r docs/javadoc/* ifarm:/group/clas/www/clasweb/html/clas12offline/docs/javadoc
1822

23+
##### generate front index page
24+
pushd $dest
25+
26+
cat > index.html << EOF
27+
<html><body bgcolor="cccccc"><head>
28+
<title>coatjava javadocs</title>
29+
<STYLE TYPE="text/css"></STYLE>
30+
</head>
31+
<p><p align="center"><b><font size="5">CLAS12 Coatjava Javadocs <br></b></font></p>
32+
<br>
33+
<br>
34+
EOF
35+
36+
pages=($(find -name "index.html" | sed 's;^\./;;' | sed 's;/index.html;;' | grep -v index.html | sort))
37+
header=""
38+
for page in ${pages[@]}; do
39+
headerTmp=$(echo $page | sed 's;/.*;;g')
40+
obj=$(echo $page | sed "s;^$headerTmp/;;")
41+
if [ "$header" != "$headerTmp" ]; then
42+
[ "$header" != "" ] && echo "</ul>" >> index.html
43+
header=$headerTmp
44+
echo "<h3>$header</h3>" >> index.html
45+
echo "<ul>" >> index.html
46+
fi
47+
echo "<li><a href=\"$page/index.html\">$obj</a></li>" >> index.html
48+
done
49+
50+
cat >> index.html << EOF
51+
</ul>
52+
</body>
53+
</html>
54+
EOF
55+
56+
popd
57+
echo "Documentation generated: $dest/index.html"

‎docs/javadoc/.gitignore‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1 @@
1-
common-tools
2-
reconstruction
1+
*

‎docs/javadoc/index.html‎

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

0 commit comments

Comments
 (0)