doc: mkdocs -> zensical

.github/workflows/ci.yml

@@ -368,12 +368,14 @@ jobs:
     runs-on: ubuntu-latest
     needs: [ unit_tests ]
     steps:
-      ### mkdocs
+      ### zensical
       - uses: actions/checkout@v7
-      - name: install mkdocs dependencies
-        run: python -m pip install -r docs/mkdocs/requirements.txt
-      - name: generate mkdocs
-        run: docs/mkdocs/generate.sh pages
+      - name: install zensical dependencies
+        run: python -m pip install -r docs/zensical/requirements.txt
+      - name: generate zensical
+        run: |
+          docs/zensical/generate.sh zensical_out
+          mv zensical_out/site pages
       ### jacoco
       - name: download jacoco report artifact
         uses: actions/download-artifact@v8

.gitlab-ci.yml

@@ -127,8 +127,8 @@ docs:
     - tar -xzf coatjava.tar.gz
     - python3 -m venv venv
     - source venv/bin/activate
-    - python3 -m pip install -r docs/mkdocs/requirements.txt
-    - ./docs/mkdocs/generate.sh pages
+    - python3 -m pip install -r docs/zensical/requirements.txt
+    - ./docs/zensical/generate.sh pages
     - libexec/build-javadocs.sh
     - ls -l && ls -l pages && ls -l publish
     - mv target/reports/apidocs pages/javadoc

docs/mkdocs/docs/index.md → docs/zensical/docs/index.md

@@ -2,7 +2,7 @@
 
 ## Documentation
 
-| | |
+| Table of Contents | |
 | --- | --- |
 | [**API Documentation**](javadoc/index.html) | Documentation for classes and methods |
 | [**HIPO Banks**](banks.md) | Bank descriptions |

docs/zensical/generate.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# generate the documentation
+if [ $# -ne 1 ]; then
+  echo "USAGE: $0 [output_dir]" >&2
+  echo "WARNING: the [output_dir] will be REMOVED before generation!" >&2
+  exit 2
+fi
+
+# make output directory
+output_dir=$(realpath $1)
+mkdir -p $output_dir
+rm -rv $output_dir
+mkdir -p $output_dir
+echo '*' > $output_dir/.gitignore
+
+# source directories
+src_dir=$(dirname $0)
+top_dir=$src_dir/../..
+
+# generate build files
+cp $src_dir/zensical.toml $output_dir/
+cp -r $src_dir/docs $output_dir/
+$src_dir/src/banks.rb $top_dir/etc/bankdefs/hipo4 $output_dir/docs
+
+# build
+zensical build --config-file $output_dir/zensical.toml
+# tree $output_dir
+echo """
+Done; if you want to serve it locally, run:
+  zensical serve --config-file $output_dir/zensical.toml
+"""

docs/zensical/requirements.txt

@@ -0,0 +1 @@
+zensical==0.0.55

docs/zensical/zensical.toml

@@ -0,0 +1,57 @@
+[project]
+site_name          = "COATJAVA"
+repo_url           = "https://github.com/JeffersonLab/coatjava"
+use_directory_urls = false
+extra              = { homepage = "index.html" }
+nav = [
+  { "Home"        = "index.md" },
+  { "HIPO Banks"  = "banks.md" },
+  { "Setup Guide" = "setup.md" },
+]
+
+[project.theme]
+variant = "classic"
+logo = "logo.png"
+favicon = "logo.png"
+features = [
+  "content.code.copy",
+  "content.code.select",
+  "content.tooltips",
+  "search.suggest",
+]
+[[project.theme.palette]]
+media       = "(prefers-color-scheme)"
+primary     = "purple"
+accent      = "deep orange"
+toggle.icon = "material/brightness-auto"
+toggle.name = "Switch to light mode"
+[[project.theme.palette]]
+media       = "(prefers-color-scheme: light)"
+scheme      = "default"
+primary     = "purple"
+accent      = "deep orange"
+toggle.icon = "material/weather-sunny"
+toggle.name = "Switch to dark mode"
+[[project.theme.palette]]
+media       = "(prefers-color-scheme: dark)"
+scheme      = "slate"
+primary     = "purple"
+accent      = "orange"
+toggle.icon = "material/weather-night"
+toggle.name = "Switch to system preference"
+
+[project.plugins]
+search = {}
+
+[project.markdown_extensions]
+abbr = {}
+admonition = {}
+attr_list = {}
+pymdownx.inlinehilite = {}
+pymdownx.snippets = {}
+pymdownx.details = {}
+"pymdownx.highlight" = { anchor_linenums = true, line_spans = "__span", pygments_lang_class = true }
+[[project.markdown_extensions."pymdownx.superfences".custom_fences]]
+name   = "mermaid"
+class  = "mermaid"
+format = "pymdownx.superfences.fence_code_format"