feat: generate mkdocs webpage, and get rid of pre-commit

.github/workflows/ci.yml

@@ -173,55 +173,46 @@ jobs:
       - name: pass
         run: exit 0
 
-  # generate documentation
+  # documentation
   #############################################################################
 
   generate_documentation:
     runs-on: ubuntu-latest
+    needs: [ build ]
     steps:
+      ### mkdocs
       - uses: actions/checkout@v4
-      - name: Set up JDK
-        uses: actions/setup-java@v4
-        with:
-          java-version: ${{ env.javadoc_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.ref == 'refs/heads/development' }}
-    needs: [ build, generate_documentation ]
-    runs-on: ubuntu-latest
-    steps:
-      - name: download jacoco report
+      - name: install mkdocs dependencies
+        run: python -m pip install -r docs/mkdocs/requirements.txt
+      - name: generate mkdocs
+        run: docs/mkdocs/generate.sh pages
+      ### jacoco
+      - name: download jacoco report artifact
         uses: actions/download-artifact@v4
         with:
           name: jacoco_report
           path: pages/jacoco
-      - name: download javadoc documentation
-        uses: actions/download-artifact@v4
+      ### javadoc
+      - name: set up JDK
+        uses: actions/setup-java@v4
         with:
-          name: javadoc
-          path: pages/javadoc
-      - run: tree pages
+          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/
+      ### upload artifacts
       - uses: actions/upload-pages-artifact@v3
         with:
-          retention-days: 1
+          retention-days: 7
           path: pages/
 
   deploy_web_pages:
     if: ${{ github.ref == 'refs/heads/development' }}
-    needs: collect_webpages
+    needs: [ generate_documentation ]
     permissions:
       pages: write
       id-token: write

README.md

@@ -3,6 +3,7 @@
 [![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/jacoco)
 
+- [**Documentation Homepage**](https://jeffersonlab.github.io/coatjava)
 - [API Documentation (Javadoc)](https://jeffersonlab.github.io/coatjava/javadoc)
 
 ----

docs/mkdocs/docs/index.md

@@ -0,0 +1,14 @@
+# COATJAVA
+
+## Documentation
+
+| | |
+| --- | --- |
+| [**API Documentation**](javadoc/index.html) | Documentation for classes and methods |
+| [**HIPO Bank**](banks.md) | Bank descriptions |
+| [**Source code**](https://github.com/JeffersonLab/coatjava) | The source code `git` repository |
+
+---
+
+## Reports
+- [Coverage Report](jacoco/index.html)

docs/mkdocs/generate.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# generate the documentation
+if [ $# -ne 1 ]; then
+  echo "USAGE: $0 [output_dir]" >&2
+  exit 2
+fi
+
+# make output dir
+output_dir=$(realpath $1)
+mkdir -p $output_dir
+
+# make build directory
+build_dir=${output_dir}__build
+mkdir -p $build_dir
+rm -r $build_dir
+mkdir -p $build_dir
+
+# source directories
+src_dir=$(dirname $0)
+top_dir=$src_dir/../..
+
+# generate build files
+cp $src_dir/mkdocs.yaml $build_dir/
+cp -r $src_dir/docs $build_dir/
+$src_dir/src/banks.rb $top_dir/etc/bankdefs/hipo4 > $build_dir/docs/banks.md
+tree $build_dir
+
+# build
+mkdocs build --config-file $build_dir/mkdocs.yaml --site-dir $output_dir
+tree $output_dir

docs/mkdocs/mkdocs.yaml

@@ -0,0 +1,10 @@
+site_name: COATJAVA Documentation
+nav:
+  - Home: index.md
+  - HIPO Bank Definitions: banks.md
+use_directory_urls: false
+extra:
+  homepage: index.html
+theme:
+  name: mkdocs
+  user_color_mode_toggle: auto

docs/mkdocs/requirements.txt

@@ -0,0 +1 @@
+mkdocs>=1.6.1

.github/make_banks_readme.rb → docs/mkdocs/src/banks.rb

@@ -51,8 +51,7 @@
 # dump a table
 puts """# Bank Group and Item IDs
 
-> [!NOTE]
-> Iguana banks, which are defined in the Iguana repository, use group number 30000.
+> **NOTE:**  Iguana banks, which are defined in the Iguana repository, use group number 30000.
 
 """