fix: conform to clas12-mcgen requirements (#10)

JeffersonLab · Jun 4, 2024 · fda7471 · fda7471
1 parent acd5a38
commit fda7471
Show file tree

Hide file tree

Showing 9 changed files with 215 additions and 81 deletions.
diff --git a/.github/generate_usage_guide.sh b/.github/generate_usage_guide.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+if [ $# -ne 1 ]; then
+  echo "USAGE: $0 [EXECUTABLE]" >&2
+  exit 1
+fi
+
+$1 --help |\
+  perl -pe 's/(--.*?)([^a-zA-Z-])/<font color="#ff00ff">$1<\/font>$2/g' |\
+  perl -pe 's/(^[^\s].*:)/<font color="#ffffff">$1<\/font>/' |\
+  sed 's;https://github.com.*;<a href="&">&</a>;g' \
+  > tmp_usage
+
+date > tmp_date
+
+cat $(dirname $0)/usage.html |\
+  sed $'/@usage@/{r tmp_usage\nd}' |\
+  sed $'/@date@/{r tmp_date\nd}'
+
+rm -f tmp_usage tmp_date
diff --git a/.github/usage.html b/.github/usage.html
@@ -0,0 +1,68 @@
+<html>
+  <head>
+    <title>clas-stringspinner usage guide</title>
+    <style>
+      body {
+        background-color: #002222;
+        color: #ffffff;
+      }
+      a {
+        color: #00cccc;
+      }
+      .sec {
+        background-color: #330033;
+        color: #ffffff;
+        width: 1000px;
+        padding: 10px;
+        margin: auto;
+        border: 5px solid gray;
+      }
+      code {
+        font-family: Consolas,"courier new";
+        font-weight: bold;
+        color: #00dd00;
+        background-color: #220022;
+        padding: 2px;
+        font-size: 105%;
+      }
+      .codeblock {
+        padding: 5px;
+        width: 980px;
+        background-color: #220022;
+        border: 2px solid green
+      }
+    </style>
+  </head>
+<body>
+
+<center><h1>Running StringSpinner</h1></center>
+
+<div class="sec">
+<h2>Executable</h2>
+The main executable <code>clas-stringspinner</code> is installed in <code>$install_dir/bin</code> (unless you have changed the <code>bindir</code> build option).
+See below for the <b>Usage Guide</b>, or run:<br/><br/>
+<div class="codeblock">
+<pre><code>$install_dir/bin/clas-stringspinner --help</code></pre>
+</div>
+<ul>
+  <li><b>TIP:</b> For easier usage, add the installed <code>$install_dir/bin</code> directory to your <code>$PATH</code></li>
+  <li><b>NOTE:</b> No environment variables are required to run <code>clas-stringspinner</code></li>
+</ul>
+</div>
+
+<br/>
+
+<div class="sec">
+<h2>Usage Guide</h2>
+<div class="codeblock">
+<pre><code>
+@usage@
+</code></pre>
+</div>
+</div>
+<center>Last updated:
+@date@
+</center>
+<br/>
+</body>
+</html>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -35,6 +35,7 @@ jobs:
             pkgconf
             pythia8
             python
+            perl
             tree
           )
           pacman -S --noconfirm ${pkgs[*]}
@@ -54,13 +55,39 @@ jobs:
       - run: meson test
         working-directory: build
       - name: test installation
-        run: install/bin/stringspinner --num-events 1
+        run: install/bin/clas-stringspinner --num-events 1
+      - name: test OSG options
+        run: install/bin/clas-stringspinner --trig 10 --docker --seed 1448577483 # see `clas12-mcgen` documentation
       - name: test relocatability
         run: |
           mkdir relocated
           cp -r install relocated/
-          relocated/install/bin/stringspinner --num-events 1
+          relocated/install/bin/clas-stringspinner --num-events 1
       - name: test symlinking
         run: |
-          ln -sv install/bin/stringspinner
-          ./stringspinner --num-events 1
+          ln -sv install/bin/clas-stringspinner
+          ./clas-stringspinner --num-events 1
+      - name: generate documentation
+        run: |
+          mkdir publish
+          .github/generate_usage_guide.sh install/bin/clas-stringspinner |& tee publish/index.html
+      - name: upload documentation
+        uses: actions/upload-pages-artifact@v3
+        with:
+          retention-days: 3
+          path: publish/
+
+  deploy_webpages:
+    if: ${{ github.ref == 'refs/heads/main' }}
+    needs: stringspinner
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: deployment
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 /.cache
 /install*
 *.lund
+*.dat
diff --git a/README.md b/README.md
@@ -1,59 +1,8 @@
 # clas-stringspinner
 [StringSpinner](https://gitlab.com/albikerbizi/stringspinner) wrapper for CLAS
 
-## Dependencies
-
-- [Pythia 8](https://pythia.org/)
-- [fmt](https://fmt.dev/)
-- [meson](https://mesonbuild.com/)
-- [ninja](https://ninja-build.org/)
-- [StringSpinner](https://gitlab.com/albikerbizi/stringspinner) is already included as a `git` submodule
-
-## Building
-
-Build using `meson`. For example, let
-- `$source_dir` be this `clas-stringspinner` source code directory (contains this `README.md`)
-- `$build_dir` be the build directory (will be created)
-- `$install_dir` be the installation destination, which must be an absolute path (will be created)
-
-1. Setup the build directory:
-```bash
-meson setup $build_dir $source_dir --prefix $install_dir
-```
-2. Set build options (see **Build Options** section below); the defaults should be sufficient for most users, so this step is **optional**.
-3. Build and install:
-```bash
-meson install -C $build_dir
-```
-4. Test:
-```bash
-meson test -C $build_dir
-```
-
-### Build options
-
-In addition to the built-in options, the following table shows the project options:
-
-| Option                          | Description                                                                                            |
-| ---                             | ---                                                                                                    |
-| `stringspinner:install_example` | Install the [StringSpinner example](https://gitlab.com/albikerbizi/stringspinner/-/blob/master/dis.cc) |
-
-For more details and current option values, run
-```bash
-meson configure $build_dir
-```
-To set a build option named `opt` to value `val`, run:
-```bash
-meson configure $build_dir -D opt=val
-```
-
-## Running StringSpinner
-
-The installed binary `stringspinner` is the main executable Monte Carlo generator; assuming you have not changed certain build options, run
-```bash
-$install_dir/bin/stringspinner --help
-```
-for the usage guide.
-
-> [!TIP]
-> For easier usage, add the installed `$install_dir/bin` directory to your `$PATH`, or make a symbolic link pointing to the `stringspinner` executable.
+| Documentation |
+| --- |
+| [Setup Guide](/doc/setup.md) |
+| [Usage Guide](https://jeffersonlab.github.io/clas-stringspinner) |
+| [Configuration Files](/config) |
diff --git a/config/README.md b/config/README.md
@@ -1,3 +1,6 @@
 # Pythia Configuration Files
 
-If you add a new file here, re-run `meson install` to install it so that `stringspinner` can find it.
+This directory contains configuration files for setting Pythia parameters.
+
+> [!NOTE]
+> If you add a new file here, re-run `meson install` to install it so that `clas-stringspinner` can find it.
diff --git a/doc/setup.md b/doc/setup.md
@@ -0,0 +1,47 @@
+# Setup Guide
+
+## Dependencies
+
+- [Pythia 8](https://pythia.org/)
+- [fmt](https://fmt.dev/)
+- [meson](https://mesonbuild.com/)
+- [ninja](https://ninja-build.org/)
+- [StringSpinner](https://gitlab.com/albikerbizi/stringspinner) is already included as a `git` submodule
+
+## Building
+
+Build using `meson`. For example, let
+- `$source_dir` be this `clas-stringspinner` source code directory (contains this `README.md`)
+- `$build_dir` be the build directory (will be created)
+- `$install_dir` be the installation destination, which must be an absolute path (will be created)
+
+1. Setup the build directory:
+```bash
+meson setup $build_dir $source_dir --prefix $install_dir
+```
+2. Set build options (see **Build Options** section below); the defaults should be sufficient for most users, so this step is **optional**.
+3. Build and install:
+```bash
+meson install -C $build_dir
+```
+4. Test:
+```bash
+meson test -C $build_dir
+```
+
+### Build options
+
+In addition to the built-in options, the following table shows the project options:
+
+| Option                          | Description                                                                                            |
+| ---                             | ---                                                                                                    |
+| `stringspinner:install_example` | Install the [StringSpinner example](https://gitlab.com/albikerbizi/stringspinner/-/blob/master/dis.cc) |
+
+For more details and current option values, run
+```bash
+meson configure $build_dir
+```
+To set a build option named `opt` to value `val`, run:
+```bash
+meson configure $build_dir -D opt=val
+```
diff --git a/meson.build b/meson.build
@@ -23,6 +23,7 @@ etc_dir = get_option('sysconfdir') / meson.project_name()
 add_project_arguments(
   '-DSTRINGSPINNER_ETCDIR="' + fs.relative_to(etc_dir, get_option('bindir')) + '"',
   '-DSTRINGSPINNER_PREFIX_ETCDIR="' + get_option('prefix') / etc_dir + '"',
+  '-DEXE_NAME="' + meson.project_name() + '"',
   language: ['cpp'],
 )
 install_subdir(
@@ -34,15 +35,15 @@ install_subdir(
 
 # main executable
 main_exe = executable(
-  'stringspinner',
-  'src/stringspinner.cpp',
+  meson.project_name(),
+  'src' / meson.project_name() + '.cpp',
   dependencies: [ fmt_dep, stringspinner_dep ],
   install: true,
 )
 
 # test executable
 test(
-  'stringspinner',
+  meson.project_name(),
   main_exe,
   args: [
     '--num-events', '10000',