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

Author: c-dilks

.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 renamed to 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 renamed to 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 renamed to 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.
+