Merge pull request #243 from Computer-Aided-Validation-Laboratory/dic-guide

Doc Improvements

Author: JoelPhys

docs/apidoc.sh

@@ -1,4 +1,5 @@
-set -e  
+#!/usr/bin/env bash
+set -e
 set -o pipefail
 
 echo "=========================================="
@@ -11,23 +12,16 @@ error_exit() {
     exit 1
 }
 
-# Generate the python API documentation
+# Python API documentation
 sphinx-apidoc -f -o ./source --separate ../src/pyvale/ ../src/pyvale/data/* ../src/pyvale/examples/* || error_exit "sphinx-apidoc failed"
 
 # Remove autogenerated TOC file
 rm -f source/modules.rst || error_exit "Failed to remove modules.rst"
 
-# Generate the C++ API documentation
-( cd ./source && doxygen Doxyfile ) || error_exit "doxygen generation failed"
-
 echo "Updating generated RST files..."
 
-# Change title for dataset file
-# sed -i '0,/pyvale.dataset/s/pyvale.dataset/pyvale.dataset/' source/pyvale.dataset.rst || error_exit "Failed to update dataset title"
-# sed -i '0,/dataset.dataset/s/dataset.dataset/pyvale.dataset/' source/pyvale.dataset.dataset.rst || error_exit "Failed to update dataset title"
-
 # Modules to process
-modules=("dic" "blender" "mooseherder" "sensorsim" "verif" "dataset")
+modules=("dic" "blender" "mooseherder" "sensorsim" "verif" "dataset" "strain")
 
 for mod in "${modules[@]}"; do
     rst="source/pyvale.${mod}.rst"
@@ -59,3 +53,79 @@ rm -f ./source/pyvale.dic.dic2dcpp.rst || error_exit "Failed to remove dic2dcpp.
 
 echo "PYTHON API DOCUMENTATION GENERATED SUCCESSFULLY!"
 
+# ------------------------------------------------------------------
+# Generate C++ API documentation
+# ------------------------------------------------------------------
+echo "=========================================="
+echo " GENERATING C++ API DOCUMENTATION..."
+echo "=========================================="
+
+# Run Doxygen (optional, if you still want it)
+( cd ./source && doxygen Doxyfile ) || error_exit "doxygen generation failed"
+
+# Create RST files for each C++ header
+for mod in "${modules[@]}"; do
+    src_dir="../src/pyvale/${mod}/cpp"
+    out_dir="source/cpp/${mod}"
+
+    mkdir -p "$out_dir"
+
+    for file in "$src_dir"/*.hpp; do
+        [ -e "$file" ] || continue
+
+        filename=$(basename "$file")
+        base="${filename%.hpp}"
+        rst_file="${out_dir}/${base}.rst"
+
+        echo "Generating $rst_file"
+
+        cat > "$rst_file" <<EOF
+${filename}
+==================
+
+.. doxygenfile:: ${filename}
+   :project: pyvale
+   :path: ${src_dir}
+EOF
+    done
+done
+
+# ------------------------------------------------------------------
+# Generate module-level index RST files for C++ headers
+# ------------------------------------------------------------------
+for mod in "${modules[@]}"; do
+    out_dir="source/cpp/${mod}"
+    index_file="source/cpp/cpp_${mod}.rst"
+
+    headers=""
+    for f in "$out_dir"/*.rst; do
+        [ -e "$f" ] || continue  # skip if no files
+        headers="$headers $(basename "$f")"
+    done
+
+    # Skip if no headers found
+    [ -z "$headers" ] && continue
+
+    # Sort headers alphabetically
+    headers=$(echo $headers | tr ' ' '\n' | sort)
+
+    echo "Generating module index $index_file"
+
+    {
+        echo "${mod}"
+        echo "=================="
+        echo ""
+        echo ".. toctree::"
+        echo "   :caption: C++ Source Files"
+        echo "   :maxdepth: 1"
+        echo ""
+        for h in $headers; do
+            echo "   ${mod}/${h}"
+        done
+    } > "$index_file"
+done
+
+
+
+echo "C++ RST FILES GENERATED SUCCESSFULLY!"
+

docs/requirements.txt

@@ -1,37 +1,35 @@
-# --- Core Sphinx Builder ---
+# Core Stuff
 sphinx
-babel                      # For language support/i18n
-docutils                   # For RST parsing (fundamental)
-imagesize                  # For image dimension handling
-pygments                   # For code highlighting
-snowballstemmer            # For search indexing (used by epub3 builder)
+babel
+docutils
+imagesize
+pygments
+snowballstemmer
+breathe
 
-# --- Theme and Parser ---
+# Theme
 furo
 alabaster
 myst-parser
 
-# --- Sphinx Extensions (Directly Listed in conf.py) ---
+# nice formatting stuff
 sphinx-codeautolink
 sphinx-copybutton
-breathe                    # For C++ documentation integration
-sphinx-gallery             # For example gallery generation
+sphinx-gallery
+sphinx-design
+sphinx-autodoc-typehints
+ipywidgets
+matplotlib
+pillow
 
-# --- Extension Dependencies ---
-sphinx-autodoc-typehints   # You use 'autodoc' which benefits from this
-ipywidgets                 # Often required by sphinx-gallery examples (e.g., matplotlib output)
-matplotlib                 # Required for plotting in sphinx-gallery examples
-pillow                     # Required for various image/gallery operations
-
-# --- Specific sphinxcontrib Extensions (Explicitly added to resolve previous errors) ---
-sphinxcontrib-applehelp    # Needed if the epub3 builder triggers it (which is common)
+sphinxcontrib-applehelp
 sphinxcontrib-devhelp
 sphinxcontrib-htmlhelp
 sphinxcontrib-jsmath
-sphinxcontrib-qthelp       # Added proactively for completeness
+sphinxcontrib-qthelp
 sphinxcontrib-serializinghtml
 
-# --- Your Project Dependencies (From your original list) ---
+# other random stuff
 certifi
 idna
 jinja2

docs/source/Doxyfile

@@ -943,7 +943,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../../src/pyvale/dic/cpp
+INPUT                  = ../../src/pyvale/dic/cpp ../../src/pyvale/strain/cpp
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs/source/_static/custom.css

@@ -9,3 +9,7 @@
     color: #0066cc !important; /* Monokai-style cyan */
 }
 
+.code-scroll {
+  max-height: 400px;
+  overflow: auto;
+}

docs/source/_static/hrdic.png

@@ -0,0 +1 @@
+../../../images/hrdic.png

docs/source/api_cpp.rst

@@ -2,21 +2,9 @@ Detailed C++ API
 =================
 
 
-Digital Image Correlation
--------------------------
-
-
 .. toctree::
    :maxdepth: 1
-   :caption: C++ Header Files
+   :caption: Modules
 
-   cpp/dicbruteforce
-   cpp/dicfourier
-   cpp/dicinterpolator
-   cpp/dicmain
-   cpp/dicoptimizer
-   cpp/dicrg
-   cpp/dicscanmethod
-   cpp/dicsmooth
-   cpp/dicstrain
-   cpp/dicutil
+   ./cpp/cpp_dic.rst
+   ./cpp/cpp_strain.rst

docs/source/api_py.rst

@@ -10,6 +10,7 @@ Detailed Python API
    pyvale.sensorsim
    pyvale.blender
    pyvale.dic
+   pyvale.strain
    pyvale.mooseherder
    pyvale.verif
    pyvale.dataset

docs/source/cite.rst

@@ -4,4 +4,28 @@ Citing Pyvale
 If Pyvale has contributed to your research or work please acknowledge the
 project in your academic puplications using the following citation:
 
+.. tab-set::
 
+   .. tab-item:: APA
+
+         Hirst, J., Sibson, L., Tayeb, A., Poole, B., Sampson, M., Bielajewa, W., ... & Fletcher, L. (2026). 
+         PYVALE: A Fast, Scalable, Open-Source 2D Digital Image Correlation (DIC) Engine 
+         Capable of Handling Gigapixel Images. 
+         *arXiv preprint arXiv:2601.12941*.
+
+   .. tab-item:: MLA
+
+         Hirst, Joel, et al. "PYVALE: A Fast, Scalable, Open-Source 2D Digital Image Correlation 
+         (DIC) Engine Capable of Handling Gigapixel Images." 
+         *arXiv preprint arXiv:2601.12941* (2026).
+
+   .. tab-item:: Bibtex
+
+      .. code-block::
+
+         @article{pyvale2026,
+            title={PYVALE: A Fast, Scalable, Open-Source 2D Digital Image Correlation (DIC) Engine Capable of Handling Gigapixel Images},
+            author={Hirst, Joel and Sibson, Lorna and Tayeb, Adel and Poole, Ben and Sampson, Megan and Bielajewa, Wiera and Atkinson, Michael and Marsh, Alex and Spencer, Rory and Hamill, Rob and others},
+            journal={arXiv preprint arXiv:2601.12941},
+            year={2026}
+        }

docs/source/conf.py

@@ -28,10 +28,13 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
-    'sphinx.ext.viewcode',  # Adds source code links
+    'sphinx.ext.intersphinx',
+    'sphinx_design',
+    'sphinx.ext.viewcode',
     'sphinx_codeautolink',
     'sphinx_copybutton',
     'sphinx_gallery.gen_gallery',
+    'sphinx.ext.mathjax',
     'breathe',
     'myst_parser'
 ]