doc: generate documentation webpage for each tag

.github/workflows/ci.yml

@@ -71,7 +71,6 @@ jobs:
           - undefined-sanitizer
           - leak-sanitizer
           - coverage
-          - documentation
           - noROOT
         include:
           # main C++ test
@@ -88,7 +87,6 @@ jobs:
           - { id: leak-sanitizer,      image: base_root, CC: clang, CXX: clang++, opts: -Dbuildtype=debug -Dz_require_root=true -Db_sanitize=leak      -Db_lundef=false -Db_pie=true }
           # misc.
           - { id: coverage,      image: base_root, CC: gcc, CXX: g++, opts: -Dbuildtype=release -Dz_require_root=true  -Db_coverage=true  -Dz_test_multithreading=false }
-          - { id: documentation, image: base_root, CC: gcc, CXX: g++, opts: -Dbuildtype=release -Dz_require_root=true  -Dinstall_documentation=true }
           - { id: noROOT,        image: base,      CC: gcc, CXX: g++, opts: -Dbuildtype=release -Dz_require_root=false }
     runs-on: ubuntu-latest
     container:
@@ -119,7 +117,7 @@ jobs:
       ###### for iguana
       - name: install packages for iguana
         run: |
-          pacman -Syu --noconfirm
+          pacman -Sy --noconfirm
           pacman -S --noconfirm \
             fmt \
             yaml-cpp
@@ -131,13 +129,6 @@ jobs:
             python-colorlog \
             python-pygments \
             gcovr
-      ###### for doxygen
-      - name: install doxygen
-        if: ${{ matrix.id == 'documentation' }}
-        run: |
-          pacman -S --noconfirm \
-            doxygen \
-            graphviz
       ###### for python bindings
       - name: install python bindings dependencies
         if: ${{ matrix.id == 'python' }}
@@ -190,7 +181,6 @@ jobs:
       - run: tree iguana
       ### run tests
       - name: meson test
-        if: ${{ matrix.id != 'documentation' }}
         working-directory: iguana_build
         run: |
           if [ "${{ env.verbose_test }}" = "true" ]; then
@@ -334,45 +324,139 @@ jobs:
           name: ${{ steps.artifact_names.outputs.validation_name }}
           retention-days: 90
           path: validation_results
+
+  # documentation
+  #########################################################
+
+  index_documentation:
+    name: Index documentation
+    runs-on: ubuntu-latest
+    outputs:
+      versions: ${{ steps.versions.outputs.versions }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      ### get list of versions from git tags; exclude old versions
+      - name: get versions for documentation generation
+        id: versions
+        run: |
+          echo main | tee version_list
+          git tag --list --sort=-v:refname |\
+            grep -v v0.1.0 |\
+            grep -v v0.2.0 |\
+            grep -v v0.3.0 |\
+            grep -v v0.4.0 |\
+            grep -v v0.4.1 |\
+            grep -v v0.5.0 |\
+            grep -v v0.6.0 |\
+            grep -v v0.7.0 |\
+            grep -v v0.7.1 |\
+            tee -a version_list
+          versions=$(cat version_list | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          echo "versions=$versions" | tee -a $GITHUB_OUTPUT
+      ### dependencies
+      - name: install packages for mkdocs
+        run: python -m pip install -r doc/mkdocs/requirements.txt
+      ### front index page
+      - name: mkdocs
+        run: doc/mkdocs/generate.sh build_mkdocs pages $(cat version_list)
+      - run: tree pages
+      ### artifacts
       - name: upload documentation artifacts
         uses: actions/upload-artifact@v5
-        if: ${{ matrix.id == 'documentation' }}
         with:
-          name: doc_doxygen
+          name: doc_web
           retention-days: 5
-          path: iguana/share/doc/iguana/html/
+          path: pages
+
+  generate_documentation:
+    name: Generate documentation
+    needs: [ index_documentation ]
+    runs-on: ubuntu-latest
+    container:
+      image: codecr.jlab.org/hallb/clas12/container-forge/base_root:latest
+      options: --user root
+    strategy:
+      matrix:
+        version: ${{ fromJson(needs.index_documentation.outputs.versions) }}
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ matrix.version }}
+          path: iguana_src
+      ### dependencies
+      - name: install packages for iguana and doxygen
+        run: |
+          pacman -Sy --noconfirm
+          pacman -S --noconfirm \
+            doxygen \
+            fmt \
+            graphviz \
+            yaml-cpp
+      ### build
+      - name: set main version to latest
+        if: ${{ matrix.version == 'main' }}
+        working-directory: iguana_src
+        run: sed -i 's;^PROJECT_NUMBER.*=.*;PROJECT_NUMBER = "LATEST";' $(find doc -name Doxyfile.in)
+      - name: meson setup
+        run: |
+          meson setup iguana_build iguana_src \
+            --prefix=$GITHUB_WORKSPACE/iguana \
+            -Drcdb:home=$RCDB_HOME \
+            -Dz_require_rcdb=true \
+            -Dz_require_root=true \
+            -Dinstall_examples=false \
+            -Dinstall_documentation=true
+      - run: meson compile
+        working-directory: iguana_build
+      - run: meson install
+        working-directory: iguana_build
+      - name: rename directory
+        run: |
+          mkdir pages
+          cd pages
+          mkdir ${{ matrix.version }}
+          mv ../iguana/share/doc/iguana/html/* ${{ matrix.version }}/
+      - name: rename latest
+        if: ${{ matrix.version == 'main' }}
+        working-directory: pages
+        run: mv main latest
+      ### artifacts
+      - name: upload documentation artifacts
+        uses: actions/upload-artifact@v5
+        with:
+          name: doc_web_${{ matrix.version }}
+          retention-days: 5
+          path: pages
 
   # deployment
   #########################################################
 
   collect_webpages:
-    if: ${{ github.ref == 'refs/heads/main' }}
     name: Collect webpages
     needs:
       - iguana
+      - generate_documentation
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
         with:
           path: iguana_src
-      - name: download doxygen documentation
+      - name: download documentation artifacts
         uses: actions/download-artifact@v6
         with:
-          name: doc_doxygen
-          path: doxygen
+          pattern: doc_web*
+          path: pages
+          merge-multiple: true
       - name: download coverage report
         uses: actions/download-artifact@v6
         with:
           name: coverage-report
           path: coverage-report
-      - run: tree
-      - name: collect
-        run: |
-          mkdir pages
-          cp iguana_src/.github/pages-index.html pages/index.html
-          mv doxygen pages/
       - run: mv coverage-report pages/
-      - run: tree
+      - run: tree pages
       - uses: actions/upload-pages-artifact@v4
         with:
           retention-days: 5

.gitignore

@@ -19,9 +19,9 @@ chameleon-tree
 *.png
 
 # overrides
-!doc/gen/logo.png
-!doc/gen/logo_small.png
-!doc/gen/mermaid/*.png
+!doc/logo.png
+!doc/logo_small.png
+!doc/mermaid/*.png
 
 # misc. artifacts
 .DS_Store

README.md

@@ -1,32 +1,14 @@
-<img src="./doc/gen/logo.png" width=50%/>
+[![CI](https://github.com/JeffersonLab/iguana/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/JeffersonLab/iguana/actions/workflows/ci.yml)
+[![Coverage](https://badgen.net/static/coverage/report/purple)](https://jeffersonlab.github.io/iguana/coverage-report)
 
-## Iguana: Implementation Guardian of Analysis Algorithms
+---
 
-The primary goal of Iguana is to preserve and centralize common analysis algorithms, such as fiducial cuts, momentum corrections, and kinematics reconstruction.
+<img src="./doc/logo.png" width=50%/>
 
-Support is focused on HIPO data for CLAS12, but extending support to other data formats (experiments) may be feasible.
+[:star: **Documentation Homepage** :star:](https://jeffersonlab.github.io/iguana)
 
-Iguana is not a framework for _reading_ data, rather it is a set of algorithms to _mutate_ the data. For HIPO data, algorithms mutate banks. See the [API documentation](https://jeffersonlab.github.io/iguana/doxygen) for the list of available algorithms.
+### About
 
-> [!CAUTION]
-> Iguana is still in the early stages of development. Please see [the issues page](https://github.com/JeffersonLab/iguana/issues) for known issues and development plans.
+**IGUANA**: **I**mplementation **Gu**ardian of **An**alysis **A**lgorithms
 
-## Documentation
-
-### For Users
-1. [**Iguana User's Guide**](https://jeffersonlab.github.io/iguana/doxygen)
-1. [Setup Guide - how to build and install Iguana](doc/setup.md)
-1. [Troubleshooting](doc/troubleshooting.md)
-
-#### Language Bindings
-1. [Python](/bind/python/README.md)
-1. [All others: see the Iguana User's guide](https://jeffersonlab.github.io/iguana/doxygen)
-
-### For Developers
-1. [Developing a new Algorithm](src/iguana/algorithms/example/ExampleAlgorithm/README.md)
-1. [Algorithm Tests and Validators](doc/testing.md)
-1. [Repository Maintenance](doc/maintenance.md)
-1. [Building for `cvmfs` or `ifarm`](doc/ifarm.md)
-
-## Status
-1. [Coverage Report](https://jeffersonlab.github.io/iguana/coverage-report)
+Iguana is designed to preserve and centralize common analysis algorithms, such as fiducial cuts, momentum corrections, and kinematics reconstruction, for CLAS12 HIPO data.

doc/gen/Doxyfile.in → doc/doxygen/Doxyfile.in

@@ -61,14 +61,14 @@ PROJECT_BRIEF          = "Implementation Guardian of Analysis Algorithms"
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = @top_srcdir@/doc/gen/logo_small.png
+PROJECT_LOGO           = @top_srcdir@/doc/logo_small.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = @top_builddir@/doc/gen
+OUTPUT_DIRECTORY       = @top_builddir@/doc/doxygen
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -842,7 +842,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            = @top_srcdir@/doc/gen/DoxygenLayout.xml
+LAYOUT_FILE            = @top_srcdir@/doc/doxygen/DoxygenLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -975,8 +975,8 @@ INPUT                  = @top_srcdir@/src/ \
                          @top_builddir@/src/iguana/bankdefs \
                          @top_builddir@/src/iguana/bankdefs/BankDefs.md \
                          @top_srcdir@/bind/ \
-                         @top_srcdir@/doc/gen/ \
-                         @top_srcdir@/doc/gen/mainpage.md \
+                         @top_srcdir@/doc/doxygen/ \
+                         @top_srcdir@/doc/doxygen/mainpage.md \
                          @top_srcdir@/examples/ \
                          @top_srcdir@/src/iguana/bankdefs/iguana.json
 
@@ -1090,8 +1090,8 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = @top_srcdir@/doc/gen/logo.png \
-                         @top_srcdir@/doc/gen/mermaid/flowchart_usage.png
+IMAGE_PATH             = @top_srcdir@/doc/logo.png \
+                         @top_srcdir@/doc/mermaid/flowchart_usage.png
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1152,7 +1152,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = @top_srcdir@/doc/gen/mainpage.md
+USE_MDFILE_AS_MAINPAGE = @top_srcdir@/doc/doxygen/mainpage.md
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common