diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed489f8083..44ed865ea3 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 342de80f08..d42ca40d5f 100644 --- a/.gitlab-ci.yml +++ b/.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 diff --git a/docs/mkdocs/generate.sh b/docs/mkdocs/generate.sh deleted file mode 100755 index 74cdd27681..0000000000 --- a/docs/mkdocs/generate.sh +++ /dev/null @@ -1,33 +0,0 @@ -#!/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 -tree $build_dir - -# build -mkdocs build --config-file $build_dir/mkdocs.yaml --site-dir $output_dir -tree $output_dir diff --git a/docs/mkdocs/mkdocs.yaml b/docs/mkdocs/mkdocs.yaml deleted file mode 100644 index 8e2fd29e16..0000000000 --- a/docs/mkdocs/mkdocs.yaml +++ /dev/null @@ -1,12 +0,0 @@ -site_name: COATJAVA Documentation -nav: - - Home: index.md - - HIPO Banks: banks.md - - Setup Guide: setup.md -use_directory_urls: false -extra: - homepage: index.html -theme: - name: mkdocs - user_color_mode_toggle: auto - color_mode: auto diff --git a/docs/mkdocs/requirements.txt b/docs/mkdocs/requirements.txt deleted file mode 100644 index a5678a34b0..0000000000 --- a/docs/mkdocs/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -mkdocs>=1.6.1 diff --git a/docs/mkdocs/docs/index.md b/docs/zensical/docs/index.md similarity index 96% rename from docs/mkdocs/docs/index.md rename to docs/zensical/docs/index.md index 1dc49c17df..56daa84698 100644 --- a/docs/mkdocs/docs/index.md +++ b/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 | diff --git a/docs/zensical/docs/logo.png b/docs/zensical/docs/logo.png new file mode 100644 index 0000000000..80ab8e1949 Binary files /dev/null and b/docs/zensical/docs/logo.png differ diff --git a/docs/mkdocs/docs/setup.md b/docs/zensical/docs/setup.md similarity index 100% rename from docs/mkdocs/docs/setup.md rename to docs/zensical/docs/setup.md diff --git a/docs/zensical/generate.sh b/docs/zensical/generate.sh new file mode 100755 index 0000000000..8c30316109 --- /dev/null +++ b/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 +""" diff --git a/docs/zensical/requirements.txt b/docs/zensical/requirements.txt new file mode 100644 index 0000000000..4072cbca8e --- /dev/null +++ b/docs/zensical/requirements.txt @@ -0,0 +1 @@ +zensical==0.0.55 diff --git a/docs/mkdocs/src/banks.rb b/docs/zensical/src/banks.rb similarity index 100% rename from docs/mkdocs/src/banks.rb rename to docs/zensical/src/banks.rb diff --git a/docs/zensical/zensical.toml b/docs/zensical/zensical.toml new file mode 100644 index 0000000000..b39ec6db08 --- /dev/null +++ b/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"