feat: generate and deploy javadoc documentation (#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
JeffersonLab · Apr 19, 2024 · 48718d6 · 48718d6
1 parent 3633022
commit 48718d6
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 63 deletions.
diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
@@ -16,6 +16,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: bash
+
 env:
   java_version: 11
   java_distribution: zulu
@@ -33,8 +37,6 @@ jobs:
         runner:
           - ubuntu-latest
           - macos-latest
-    outputs:
-      default_runner: ubuntu-latest
     runs-on: ${{ matrix.runner }}
     steps:
       - uses: actions/checkout@v4
@@ -57,8 +59,9 @@ jobs:
         run: validation/jacoco-aggregate.sh
       - name: publish jacoco report
         if: ${{ matrix.runner == 'ubuntu-latest' }}
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
+          name: jacoco_report
           path: publish/
           retention-days: 1
 
@@ -110,7 +113,7 @@ jobs:
 
   test_run-groovy:
     needs: [ build ]
-    runs-on: ${{ needs.build.outputs.default_runner }}
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: Set up JDK
@@ -124,7 +127,7 @@ jobs:
           groovy-version: ${{ env.groovy_version }}
       - uses: actions/download-artifact@v4
         with:
-          name: build_${{ needs.build.outputs.default_runner }}
+          name: build_ubuntu-latest
       - name: untar build
         run: tar xzvf coatjava.tar.gz
       - name: test run-groovy
@@ -135,17 +138,60 @@ jobs:
       - build
       - test_coatjava
       - test_run-groovy
-    runs-on: ${{ needs.build.outputs.default_runner }}
+    runs-on: ubuntu-latest
     steps:
       - name: pass
         run: exit 0
 
+  # generate documentation
+  #############################################################################
+
+  generate_documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK
+        uses: actions/setup-java@v4
+        with:
+          java-version: ${{ env.java_version }}
+          distribution: ${{ env.java_distribution }}
+      - name: build
+        run: ./build-coatjava.sh
+      - name: generate documentation
+        run: ./build-javadocs.sh
+      - uses: actions/upload-artifact@v4
+        with:
+          name: javadoc
+          path: docs/javadoc/
+          retention-days: 1
+
   # deploy web pages
   #############################################################################
 
+  collect_webpages:
+    if: ${{ github.head_ref == 'development' || github.ref_name == 'development' }}
+    needs: [ build, generate_documentation ]
+    runs-on: ubuntu-latest
+    steps:
+      - name: download jacoco report
+        uses: actions/download-artifact@v4
+        with:
+          name: jacoco_report
+          path: pages/jacoco
+      - name: download javadoc documentation
+        uses: actions/download-artifact@v4
+        with:
+          name: javadoc
+          path: pages/javadoc
+      - run: tree pages
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          retention-days: 1
+          path: pages/
+
   deploy_web_pages:
-    if: ${{ github.event_name == 'push' }}
-    needs: build
+    if: ${{ github.head_ref == 'development' || github.ref_name == 'development' }}
+    needs: collect_webpages
     permissions:
       pages: write
       id-token: write

diff --git a/README.md b/README.md
@@ -1,7 +1,11 @@
 # COATJAVA
 [![Build Status](https://github.com/jeffersonlab/coatjava/workflows/Coatjava-CI/badge.svg)](https://github.com/jeffersonlab/coatjava/actions)
 [![Validation Status](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml/badge.svg)](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml)
-[![Coverage](https://badgen.net/static/JaCoCo/coverage/purple)](https://jeffersonlab.github.io/coatjava)
+[![Coverage](https://badgen.net/static/JaCoCo/coverage/purple)](https://jeffersonlab.github.io/coatjava/jacoco)
+
+- [API Documentation (Javadoc)](https://jeffersonlab.github.io/coatjava/javadoc)
+
+----
 
 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:
 
@@ -27,8 +31,6 @@ For anything more, see the "General Developer Documentation" link on that softwa
 
 The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wiki/Troubleshooting) wiki page may also still be useful but likely outdated.
 
-<!--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).-->
-
 <!--
 ## Repository Structure and Dependency Management
 ### Common Tools

diff --git a/build-javadocs.sh b/build-javadocs.sh
@@ -1,10 +1,15 @@
-#!/bin/sh
+#!/bin/bash
 #
 # surely this should be done more properly with only maven, meanwhile ...
 #
 
-mvn javadoc:javadoc -Ddoclint=none 
+set -e
 
+##### generate documentation
+mvn javadoc:javadoc -Ddoclint=none
+
+
+##### collect documentation
 src=target/site/apidocs
 dest=docs/javadoc
 
@@ -14,5 +19,39 @@ do
     cp -r $dir/* $dest/${dir%$src}
 done
 
-#scp -r docs/javadoc/* ifarm:/group/clas/www/clasweb/html/clas12offline/docs/javadoc
 
+##### generate front index page
+pushd $dest
+
+cat > index.html << EOF
+<html><body bgcolor="cccccc"><head>
+<title>coatjava javadocs</title>
+<STYLE TYPE="text/css"></STYLE>
+</head>
+<p><p align="center"><b><font size="5">CLAS12 Coatjava Javadocs <br></b></font></p>
+<br>
+<br>
+EOF
+
+pages=($(find -name "index.html" | sed 's;^\./;;' | sed 's;/index.html;;' | grep -v index.html | sort))
+header=""
+for page in ${pages[@]}; do
+  headerTmp=$(echo $page | sed 's;/.*;;g')
+  obj=$(echo $page | sed "s;^$headerTmp/;;")
+  if [ "$header" != "$headerTmp" ]; then
+    [ "$header" != "" ] && echo "</ul>" >> index.html
+    header=$headerTmp
+    echo "<h3>$header</h3>" >> index.html
+    echo "<ul>" >> index.html
+  fi
+  echo "<li><a href=\"$page/index.html\">$obj</a></li>" >> index.html
+done
+
+cat >> index.html << EOF
+</ul>
+</body>
+</html>
+EOF
+
+popd
+echo "Documentation generated: $dest/index.html"
diff --git a/docs/javadoc/.gitignore b/docs/javadoc/.gitignore
@@ -1,2 +1 @@
-common-tools
-reconstruction
+*
diff --git a/docs/javadoc/index.html b/docs/javadoc/index.html