build!: use same parent POM for all modules, and fix javadoc inter-module linking (#538)

* build: aggregate javadoc

* fix: some progress...

* fix: make sure all `pom.xml`s have a preamble

* build!: use the main parent POM for `common-tools/cnuphys`

- fixes missing UTF-8 encoding bug by making sure that
  `common-tools/cnuphys/` POMs use the same `javadoc` config as
  everything else
- a bit of scope creep here, since this is another "major" build change

* feat: use `build-coatjava.sh` to build documentation

* fix: ignore `docs/javadoc` files

for those who have generated them locally

* fix: cleanup

* fix: version num conflicts

Author: c-dilks

.github/workflows/ci.yml

@@ -199,11 +199,9 @@ jobs:
           java-version: ${{ env.javadoc_version }}
           distribution: ${{ env.java_distribution }}
       - name: build coatjava
-        run: ./build-coatjava.sh
-      - name: generate javadoc documentation
         run: |
-          ./build-javadocs.sh
-          mv docs/javadoc pages/
+          ./build-coatjava.sh --docs
+          mv coatjava/share/doc/coatjava/html/* pages/
       ### upload artifacts
       - uses: actions/upload-pages-artifact@v3
         with:

.gitignore

@@ -3,6 +3,7 @@
 /myLocalMvnRepo
 target
 /publish
+/docs/javadoc/*
 
 *.class
 *lundfiles*.dat

.gitlab-ci.yml

@@ -86,18 +86,13 @@ coatjava:singularity:
 create-pages:
   image: codecr.jlab.org/hallb/alert/coatjava/coatjava:development
   script:
-    - export MAVEN_OPTS=" -Dfile.encoding=UTF-8"
     - echo "${CI_COMMIT_REF_NAME}"
     - ls -lrth
     - mvn --version
     - java --version 
     - ls -lrth
     - pwd
-    - ls -lrth docs/javadoc
-    - ./build-javadocs.sh 
-    - ls -lrth
-    - ls -lrth docs/
-    - ls -lrth docs/javadoc
-    - mv docs/javadoc public
+    - ./build-coatjava.sh --docs
+    - mv coatjava/share/doc/coatjava/html public
   pages: true  # specifies that this is a Pages job and publishes the default public directory
 

build-coatjava.sh

@@ -4,14 +4,32 @@ set -e
 set -u
 set -o pipefail
 
-usage='''build-coatjava.sh [-h] [--help] [--quiet] [--clean] [--spotbugs] [--nomaps] [--unittests]
- - all other arguments will be passed to `mvn`, e.g., -T4 will build with 4 parallel threads'''
+usage='''build-coatjava.sh [OPTIONS]... [MAVEN_OPTIONS]...
+
+  OPTIONS
+
+   --quiet           run more quietly
+   --clean           clean up built objects and exit (does not compile)
+
+   --nomaps          do not download field maps
+
+   --docs            also build the API documentation webpages
+   --spotbugs        also run spotbugs plugin
+   --unittests       also run unit tests
+
+   --help            show this message
+
+  MAVEN_OPTIONS
+
+   all other arguments will be passed to `mvn`, e.g., -T4 will build with 4 parallel threads
+'''
 
 quiet="no"
 cleanBuild="no"
 runSpotBugs="no"
 downloadMaps="yes"
 runUnitTests="no"
+buildDocs="no"
 mvnArgs=()
 for xx in $@
 do
@@ -20,6 +38,7 @@ do
     -n)          runSpotBugs="no"   ;;
     --nomaps)    downloadMaps="no"  ;;
     --unittests) runUnitTests="yes" ;;
+    --docs)      buildDocs="yes"    ;;
     --quiet)     quiet="yes"        ;;
     --clean)     cleanBuild="yes"   ;;
     -h|--help)
@@ -116,24 +135,38 @@ mkdir -p $prefix_dir/lib/services
 # FIXME:  this is still needed by one of the tests
 cp external-dependencies/jclara-4.3-SNAPSHOT.jar $prefix_dir/lib/utils
 
+# spotbugs, unit tests
 unset CLAS12DIR
 if [ $runUnitTests == "yes" ]; then
-	$mvn install # also runs unit tests
-	if [ $? != 0 ] ; then echo "mvn install failure" ; exit 1 ; fi
+  $mvn install # also runs unit tests
+  if [ $? != 0 ] ; then echo "mvn install failure" ; exit 1 ; fi
 else
-	$mvn -Dmaven.test.skip=true install
-	if [ $? != 0 ] ; then echo "mvn install failure" ; exit 1 ; fi
+  $mvn -Dmaven.test.skip=true install
+  if [ $? != 0 ] ; then echo "mvn install failure" ; exit 1 ; fi
 fi
 
 if [ $runSpotBugs == "yes" ]; then
-	# mvn com.github.spotbugs:spotbugs-maven-plugin:spotbugs # spotbugs goal produces a report target/spotbugsXml.xml for each module
-	$mvn com.github.spotbugs:spotbugs-maven-plugin:check # check goal produces a report and produces build failed if bugs
-	# the spotbugsXml.xml file is easiest read in a web browser
-	# see http://spotbugs.readthedocs.io/en/latest/maven.html and https://spotbugs.github.io/spotbugs-maven-plugin/index.html for more info
-	if [ $? != 0 ] ; then echo "spotbugs failure" ; exit 1 ; fi
+  # mvn com.github.spotbugs:spotbugs-maven-plugin:spotbugs # spotbugs goal produces a report target/spotbugsXml.xml for each module
+  $mvn com.github.spotbugs:spotbugs-maven-plugin:check # check goal produces a report and produces build failed if bugs
+  # the spotbugsXml.xml file is easiest read in a web browser
+  # see http://spotbugs.readthedocs.io/en/latest/maven.html and https://spotbugs.github.io/spotbugs-maven-plugin/index.html for more info
+  if [ $? != 0 ] ; then echo "spotbugs failure" ; exit 1 ; fi
 fi
 
+# documentation
+if [ $buildDocs == "yes" ]; then
+  $mvn javadoc:javadoc javadoc:aggregate -Ddoclint=none
+fi
+
+# installation
 cp common-tools/coat-lib/target/coat-libs-*-SNAPSHOT.jar $prefix_dir/lib/clas/
 cp reconstruction/*/target/clas12detector-*-SNAPSHOT*.jar $prefix_dir/lib/services/
+echo "installed coatjava to: $prefix_dir"
+if [ $buildDocs == "yes" ]; then
+  doc_dir=$prefix_dir/share/doc/coatjava/html
+  mkdir -p $doc_dir
+  cp -r target/reports/apidocs/* $doc_dir/
+  echo "installed documentation to: $doc_dir"
+fi
 
 echo "COATJAVA SUCCESSFULLY BUILT !"

build-javadocs.sh

@@ -5,12 +5,12 @@
     <artifactId>magfield</artifactId>
     <version>12.0.6t-SNAPSHOT</version>
     <packaging>jar</packaging>
-    
+
     <parent>
-      <groupId>cnuphys</groupId>
-      <artifactId>cnuphys-clas12</artifactId>
-      <relativePath>../parent/pom.xml</relativePath>
-      <version>2.0-SNAPSHOT</version>
+      <groupId>org.jlab.clas</groupId>
+      <artifactId>clas12rec</artifactId>
+      <relativePath>../../../parent/pom.xml</relativePath>
+      <version>12.0.6t-SNAPSHOT</version>
     </parent>
 
     <!-- https://mvnrepository.com/artifact/org.apache.commons/commons-math3 -->