doc!: organize and rename examples, and additional small fixes (#235)

.github/workflows/ci.yml

@@ -347,60 +347,60 @@ jobs:
         run: |
           mv iguana relocated
           source relocated/bin/this_iguana.sh --verbose # do not use --githubCI option, since we want this environment to be for only this step
-          relocated/bin/iguana-example-basic test_data.hipo ${{ env.num_events }}
+          relocated/bin/iguana_ex_cpp_00_run_functions test_data.hipo ${{ env.num_events }}
           mv relocated iguana
       ### set iguana environment, since the next steps will check the iguana installation
       - name: set iguana environment
         run: source iguana/bin/this_iguana.sh --verbose --githubCI
       ### test installed examples
       ###### cpp
-      - run: iguana-example-basic test_data.hipo ${{ env.num_events }}
+      - run: iguana_ex_cpp_00_run_functions test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'cpp' }}
-      - run: iguana-example-bank-rows test_data.hipo ${{ env.num_events }}
+      - run: iguana_ex_cpp_01_action_functions test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'cpp' }}
-      - run: iguana-example-dataframes test_data.hipo ${{ env.num_events }}
+      - run: iguana_ex_cpp_dataframes test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'cpp' }}
-      - run: iguana-example-config-files iguana/etc/iguana/examples
+      - run: iguana_ex_cpp_config_files iguana/etc/iguana/examples
         if: ${{ matrix.id == 'cpp' }}
       ###### python
-      - run: iguana-example-basic.py test_data.hipo ${{ env.num_events }}
+      - run: iguana_ex_python_00_run_functions.py test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'python' }}
-      - run: iguana-example-bank-rows.py test_data.hipo ${{ env.num_events }}
+      - run: iguana_ex_python_01_action_functions.py test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'python' }}
-      - run: iguana-example-hipopy.py test_data.hipo ${{ env.num_events }}
+      - run: iguana_ex_python_hipopy.py test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'python' }}
       ###### fortran
-      - run: iguana-example-fortran test_data.hipo ${{ env.num_events }}
+      - run: iguana_ex_fortran_01_action_functions test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'fortran' }}
       ### test ROOT macro
-      - name: test iguana_example_ROOT_macro.C interpreted
-        run: root -b -q iguana_src/examples/iguana_example_ROOT_macro.C
+      - name: test iguana_ex_cpp_ROOT_macro.C interpreted
+        run: root -b -q iguana_src/examples/iguana_ex_cpp_ROOT_macro.C
         if: ${{ matrix.id == 'cpp' }}
-      - name: test iguana_example_ROOT_macro.C compiled
-        run: root -b -q iguana_src/examples/iguana_example_ROOT_macro.C+
+      - name: test iguana_ex_cpp_ROOT_macro.C compiled
+        run: root -b -q iguana_src/examples/iguana_ex_cpp_ROOT_macro.C+
         if: ${{ matrix.id == 'cpp' }}
       ### test consumers
       - name: consumer test make
         if: ${{ matrix.id == 'cpp' }}
         run: |
           make -C iguana_src/examples/build_with_make
           echo "========================================= TEST RUN ========================================="
-          iguana_src/examples/build_with_make/bin/iguana-example-basic test_data.hipo 10
+          iguana_src/examples/build_with_make/bin/iguana_ex_cpp_00_run_functions test_data.hipo 10
       - name: consumer test meson
         if: ${{ matrix.id == 'cpp' }}
         run: |
           meson setup build_consumer_meson iguana_src/examples/build_with_meson --prefix=$(pwd)/install_consumer_meson
           meson install -C build_consumer_meson
           echo "========================================= TEST RUN ========================================="
-          install_consumer_meson/bin/iguana-example-basic test_data.hipo 10
+          install_consumer_meson/bin/iguana_ex_cpp_00_run_functions test_data.hipo 10
       - name: consumer test cmake
         if: ${{ matrix.id == 'cpp' }}
         run: |
           cmake -B build_consumer_cmake -S iguana_src/examples/build_with_cmake -DCMAKE_PREFIX_PATH=$(pwd)/hipo -G Ninja --install-prefix=$(pwd)/install_consumer_cmake
           cmake --build build_consumer_cmake
           cmake --install build_consumer_cmake
           echo "========================================= TEST RUN ========================================="
-          install_consumer_cmake/bin/iguana-example-basic test_data.hipo 10
+          install_consumer_cmake/bin/iguana_ex_cpp_00_run_functions test_data.hipo 10
       ### upload artifacts
       - uses: actions/upload-artifact@v4
         if: always()

README.md

@@ -21,7 +21,7 @@ Iguana is not a framework for _reading_ data, rather it is a set of algorithms t
 
 #### Language Bindings
 1. [Python](/bind/python/README.md)
-1. [Fortran](https://jeffersonlab.github.io/iguana/doxygen/group__fortran__usage__guide.html)
+1. [All others: see the Iguana User's guide](https://jeffersonlab.github.io/iguana/doxygen)
 
 ### For Developers
 1. [Design Notes](doc/design.md)

bind/python/README.md

@@ -36,6 +36,6 @@ For Python to be able to find and use these bindings, you need to set some envir
 
 ## Running the Examples
 
-Example Python scripts are found in this directory as `iguana-example-*.py`; they will be installed in the `bin/` subdirectory.
+Example Python scripts are found in this directory as `iguana_ex_*.py`; they will be installed in the `bin/` subdirectory.
 
 Most of them are analogous to the C++ examples, but some may be specific to the Python bindings.

bind/python/iguana-example-basic.py → bind/python/iguana_ex_python_00_run_functions.py

@@ -2,9 +2,8 @@
 
 """!
 @begin_doc_example{python}
-@file iguana-example-basic.py
-@brief Python version of `iguana-example-basic.cc`
-@see `iguana-example-basic.cc` for more information
+@file iguana_ex_python_00_run_functions.py
+@brief Python version of `iguana_ex_cpp_00_run_functions.cc` (for more details, see this `.cc` file)
 @end_doc_example
 @doxygen_off
 """

bind/python/iguana-example-bank-rows.py → bind/python/iguana_ex_python_01_action_functions.py

@@ -2,9 +2,8 @@
 
 """!
 @begin_doc_example{python}
-@file iguana-example-bank-rows.py
-@brief Python version of `iguana-example-bank-rows.cc`
-@see `iguana-example-bank-rows.cc` for more information
+@file iguana_ex_python_01_action_functions.py
+@brief Python version of `iguana_ex_cpp_01_action_functions.cc` (for more details, see this `.cc` file)
 @end_doc_example
 @doxygen_off
 """

bind/python/iguana-example-hipopy.py → bind/python/iguana_ex_python_hipopy.py

@@ -2,7 +2,7 @@
 
 """!
 @begin_doc_example{python}
-@file iguana-example-hipopy.py
+@file iguana_ex_python_hipopy.py
 @brief Python iguana example using HIPOPy: https://github.com/mfmceneaney/hipopy
 @end_doc_example
 @doxygen_off

bind/python/meson.build

@@ -7,9 +7,9 @@ install_subdir(
 
 if(get_option('install_examples'))
   python_examples = [
-    'iguana-example-basic.py',
-    'iguana-example-bank-rows.py',
-    'iguana-example-hipopy.py',
+    'iguana_ex_python_00_run_functions.py',
+    'iguana_ex_python_01_action_functions.py',
+    'iguana_ex_python_hipopy.py',
   ]
   foreach example : python_examples
     install_data(

doc/gen/Doxyfile

@@ -1006,8 +1006,8 @@ INPUT_FILE_ENCODING    =
 
 FILE_PATTERNS          = *.dox \
                          *.h \
-                         iguana-example-*.cc \
-                         iguana-example-*.py \
+                         iguana_ex_*.cc \
+                         iguana_ex_*.py \
                          Bindings.cc \
                          *.f \
                          *.C

doc/gen/examples.dox

@@ -13,9 +13,13 @@ Iguana usage examples, organized by language and use cases:
 Iguana usage examples in C++
 
 See below for the list of examples.
+- If this is your first time using Iguana, start with the numbered examples
+  first, proceeding in order; since the list below is alphabetized, you may
+  start from the top.
+- Examples without a number are specific to this language, showing certain use cases
 
 @see If you use build automation tools, here is guidance on how to include and link to Iguana in your C++ project;
-they each show how build `iguana-example-basic.cc`, which "consumes" Iguana and HIPO as dependencies:
+they each show how build `iguana_ex_cpp_00_run_functions.cc`, which "consumes" Iguana and HIPO as dependencies:
 - [**Meson consumer example**](https://github.com/JeffersonLab/iguana/tree/main/examples/build_with_meson)
 - [**CMake consumer example**](https://github.com/JeffersonLab/iguana/tree/main/examples/build_with_cmake)
 - [**Makefile consumer example**](https://github.com/JeffersonLab/iguana/tree/main/examples/build_with_make)
@@ -28,6 +32,10 @@ they each show how build `iguana-example-basic.cc`, which "consumes" Iguana and
 Iguana usage examples in Python
 
 The examples here are analogous to the C++ examples
+- If this is your first time using Iguana, start with the numbered examples
+  first, proceeding in order; since the list below is alphabetized, you may
+  start from the top.
+- Examples without a number are specific to this language, showing certain use cases
 
 @see @ref examples_cpp "C++ examples"
 */

doc/gen/mainpage.md

@@ -11,12 +11,13 @@ This documentation shows how to use the Iguana algorithms.
 For more documentation, see
 - [**Documentation Front Page**](https://github.com/JeffersonLab/iguana/blob/main/README.md)
 
-## Example Analysis Code
+## Example Code in C++, Python, and Fortran
 
 To see Iguana algorithms used in the context of analysis code, with **various languages** and **use cases**, see:
-
 - \ref examples_frontpage "Examples of Analysis Code"
 
+**NOTE:** If you're not familiar with Iguana, please read the sections below first.
+
 ## Algorithms
 
 An Iguana algorithm is a function that maps input HIPO bank data to output data. The available algorithms are:
@@ -35,7 +36,7 @@ The algorithm types are defined based on what they do to HIPO bank data:
 Most algorithms are configurable:
 - [**Algorithm Configuration Guide**](https://github.com/JeffersonLab/iguana/blob/main/doc/configuration.md)
 
-## Common Functions: for HIPO C++ Users
+### Algorithm Common Functions: for HIPO C++ Users
 
 All algorithms have the following functions, which may be used in analysis code
 that uses [**the HIPO C++ API**](https://github.com/gavalian/hipo); for
@@ -47,7 +48,7 @@ analysis code that does not, skip to the **Action Functions** section.
 <tr><td> `iguana::Algorithm::Stop` </td><td> Run after event processing </td></tr>
 </table>
 
-## Action Functions: for All Users
+### Algorithm Action Functions: for All Users
 
 The action functions do the _real_ work of the algorithm, and are meant to be
 easily callable from _any_ analysis, even if HIPO banks are not directly used.
@@ -76,3 +77,4 @@ Inputs and outputs are scalar or vector quantities.
 To maximize compatibility with user analysis code, these functions are
 overloaded, _e.g._, for every scalar function there is a corresponding vector
 function that calls it on each element of its input vectors.
+

doc/setup.md

@@ -9,7 +9,7 @@
 <a name="dependencies"></a>
 ## 🟠 Dependencies
 
-The following sections (🔶) list the dependencies and how to obtain them.
+The following sections (🟩) list the dependencies and how to obtain them.
 
 > [!TIP]
 > It's generally better to use your a package manager to install most dependencies, _e.g._:
@@ -24,25 +24,25 @@ The following sections (🔶) list the dependencies and how to obtain them.
 > git checkout 1.0.0                                               # checkout the tag '1.0.0'
 > ```
 
-### 🔶 `meson`: Build system used by Iguana
+### 🟩 `meson`: Build system used by Iguana
 <https://mesonbuild.com/>
 - Likely available in your package manager, but the latest version is preferred and may be installed with `pip`:
 ```bash
 python -m pip install meson ninja
 ```
 This includes [`ninja`](https://ninja-build.org/), which `meson` will benefit from using. 
 
-### 🔶 `fmt`: C++ output formatting library
+### 🟩 `fmt`: C++ output formatting library
 <https://github.com/fmtlib/fmt>
 - Likely available in your package manager, likely as `fmt` or `libfmt`
   - If you need Python bindings on macOS, please install `fmt` with `brew install fmt`
   - If you compile it yourself on Linux, include the `cmake` option `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` to build the static library
 
-### 🔶 `yaml-cpp`: YAML parser and emitter
+### 🟩 `yaml-cpp`: YAML parser and emitter
 <https://github.com/jbeder/yaml-cpp>
 - Likely available in your package manager, likely as `yaml-cpp`
 
-### 🔶 `hipo`: C++ HIPO API
+### 🟩 `hipo`: C++ HIPO API
 <https://github.com/gavalian/hipo>
 - Use the `hipo` module on `ifarm`, or obtain and build it yourself
 - Example `cmake` commands:
@@ -52,7 +52,7 @@ cmake --build build-hipo
 cmake --install build-hipo
 ```
 
-### 🔶 Optional: `ROOT`: Data analysis framework
+### 🟩 Optional: `ROOT`: Data analysis framework
 <https://root.cern.ch/>
 - ROOT is an **optional** dependency: some algorithms and test code depends on ROOT, but if you do not
   have ROOT on your system, `iguana` will build everything _except_ ROOT-dependent code

doc/testing.md

@@ -1,9 +1,9 @@
 # Testing and Validating Algorithms
 
 There are 2 ways to run tests:
-- `iguana-test`: an installed executable used for running single tests; this offers more control at the expense of
+- `iguana_test`: an installed executable used for running single tests; this offers more control at the expense of
   being less user friendly
-- `meson test`: user-friendly automation of `iguana-test`
+- `meson test`: user-friendly automation of `iguana_test`
 
 > [!IMPORTANT]
 > Both of these assume you are currently in your **build directory**.
@@ -14,21 +14,21 @@ There are 2 ways to run tests:
 > (CI), so if you are developing and you submit a pull requests, you may rely
 > on the CI logs to check if the tests were successful
 
-## `iguana-test`
+## `iguana_test`
 
-`iguana-test` is found both in the installation's `bin/` directory and in your build directory,
+`iguana_test` is found both in the installation's `bin/` directory and in your build directory,
 ```bash
-src/iguana/tests/iguana-test   # assuming your build directory layout is 'mirror' (the default)
+src/iguana/tests/iguana_test   # assuming your build directory layout is 'mirror' (the default)
 ```
-Run `iguana-test` for a usage guide:
+Run `iguana_test` for a usage guide:
 ```bash
-src/iguana/tests/iguana-test            # usage guide
-src/iguana/tests/iguana-test validator  # usage of the 'validator' command
-src/iguana/tests/iguana-test algorithm  # usage of the 'algorithm' command
+src/iguana/tests/iguana_test            # usage guide
+src/iguana/tests/iguana_test validator  # usage of the 'validator' command
+src/iguana/tests/iguana_test algorithm  # usage of the 'algorithm' command
 ```
 For example,
 ```bash
-src/iguana/tests/iguana-test validator -f ../data.hipo -n 0 -a clas12::MomentumCorrectionValidator -o ../validator_output
+src/iguana/tests/iguana_test validator -f ../data.hipo -n 0 -a clas12::MomentumCorrectionValidator -o ../validator_output
 ```
 will run the validator `MomentumCorrectionValidator` using data from
 `../data.hipo` and write its output to `../validator_output/`.
@@ -59,19 +59,19 @@ meson test validator-clas12-MyAlgorithm --verbose # run and show output (stdout
 ```
 If you have not supplied the required arguments, in particular the input data
 file, the test will fail. For the `validator` and `algorithm` test suites,
-`iguana-test validator` and `iguana-test algorithm` are the respective
+`iguana_test validator` and `iguana_test algorithm` are the respective
 underlying test executable commands; you may pass arguments to them using the
 `--test-args` option; for example:
 ```bash
 meson test validator-clas12-MyAlgorithm --verbose --test-args '\-f ../my_hipo_file.hipo \-n 300 \-o ../validator_output'
 ```
-See above for `iguana-test` usage guidance.
+See above for `iguana_test` usage guidance.
 
 > [!NOTE]
 > Note the usage of an escaped hyphen, `\-` instead of `-`; depending on your system, you may or may not need to use escaped hyphens in
 > `--test-args` arguments, otherwise you will see errors such as `argument --test-args: expected one argument`.
 
-Alternatively to using `--test-args`, you may set _default_ `iguana-test`
+Alternatively to using `--test-args`, you may set _default_ `iguana_test`
 arguments using Iguana **build options**:
 - The options that are relevant for tests are prefixed by `test_`
 - Set options using `meson configure` and re-running `meson install`

examples/README.md

@@ -4,7 +4,7 @@ All of the examples (`*.cc`) in [this `examples/` directory](/examples) may be b
 option `install_examples` is set to `True`. They will be installed in the `bin/`
 subdirectory of your Iguana installation. Read the example code to understand how to use Iguana, or
 
-- [View the Examples Documentation](https://jeffersonlab.github.io/iguana/doxygen/group__examples.html)
+- [View the Iguana User's Guide](https://jeffersonlab.github.io/iguana/doxygen)
 
 If you would like to integrate Iguana into an existing analysis, you'll need
 to add Iguana as a dependency. The following subdirectories are

examples/build_with_cmake/CMakeLists.txt

@@ -18,7 +18,7 @@ pkg_check_modules(hipo4 REQUIRED IMPORTED_TARGET hipo4)
 pkg_check_modules(iguana REQUIRED IMPORTED_TARGET iguana)
 
 # build and install the executable
-set(EXAMPLE_BIN iguana-example-basic)
+set(EXAMPLE_BIN iguana_ex_cpp_00_run_functions)
 add_executable(${EXAMPLE_BIN})
 target_sources(${EXAMPLE_BIN} PRIVATE ${EXAMPLE_BIN}.cc)
 target_link_libraries(${EXAMPLE_BIN} PUBLIC PkgConfig::iguana PkgConfig::hipo4)

examples/build_with_cmake/iguana_ex_cpp_00_run_functions.cc

@@ -0,0 +1 @@
+../iguana_ex_cpp_00_run_functions.cc

examples/build_with_make/iguana_ex_cpp_00_run_functions.cc

@@ -0,0 +1 @@
+../iguana_ex_cpp_00_run_functions.cc

examples/build_with_meson/iguana_ex_cpp_00_run_functions.cc

@@ -0,0 +1 @@
+../iguana_ex_cpp_00_run_functions.cc

examples/build_with_meson/meson.build

@@ -11,7 +11,7 @@ hipo_dep   = dependency('hipo4')
 iguana_dep = dependency('iguana')
 
 # build and install the executable
-example_bin = 'iguana-example-basic'
+example_bin = 'iguana_ex_cpp_00_run_functions'
 executable(
   example_bin,
   example_bin + '.cc',

examples/iguana-example-basic.cc → examples/iguana_ex_cpp_00_run_functions.cc

@@ -1,10 +1,10 @@
 /// @begin_doc_example{cpp}
-/// @file iguana-example-basic.cc
-/// @brief Example using full HIPO banks with Iguana This example requires the
-/// user to have the C++ `hipo::bank` objects; see other examples if you do not have these banks in this format.
+/// @file iguana_ex_cpp_00_run_functions.cc
+/// @brief Example using **full HIPO banks** with Iguana algorithms' `Run` functions. This example requires the
+/// user to have the C++ `hipo::bank` objects; see other examples if you do not have banks in this format.
 /// @par Usage
 /// ```bash
-/// iguana-example-basic [HIPO_FILE] [NUM_EVENTS]
+/// iguana_ex_cpp_00_run_functions [HIPO_FILE] [NUM_EVENTS]
 ///
 ///   HIPO_FILE   the HIPO file to analyze
 ///