Doc Improvements #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

JoelPhys merged 26 commits into dev from dic-guide

Feb 3, 2026

docs/apidoc.sh

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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

-Original file line number
+Diff line change
@@ Expand Up / @@ -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
@@ Expand Down @@

docs/source/_static/custom.css

-Original file line number
+Diff line change
@@ Expand Up / @@ -9,3 +9,7 @@ @@
         color: #0066cc !important; /* Monokai-style cyan */
     }
+    .code-scroll {
+      max-height: 400px;
+      overflow: auto;
+    }

docs/source/_static/hrdic.png

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		../../../images/hrdic.png

docs/source/api_cpp.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -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

-Original file line number
+Diff line change
@@ Expand Up / @@ -10,6 +10,7 @@ Detailed Python API @@
        pyvale.sensorsim
        pyvale.blender
        pyvale.dic
+       pyvale.strain
        pyvale.mooseherder
        pyvale.verif
        pyvale.dataset
@@ Expand Down @@

docs/source/cite.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -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

-Original file line number
+Diff line change
@@ Expand Up / @@ -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'
     ]
@@ Expand Down @@

docs/source/cpp/dicbruteforce.rst

This file was deleted.

docs/source/cpp/dicfourier.rst

This file was deleted.

docs/source/cpp/dicinterpolator.rst

This file was deleted.

docs/source/cpp/dicmain.rst

This file was deleted.

docs/source/cpp/dicoptimizer.rst

This file was deleted.

docs/source/cpp/dicrg.rst

This file was deleted.

docs/source/cpp/dicscanmethod.rst

This file was deleted.

docs/source/cpp/dicsmooth.rst

This file was deleted.

docs/source/cpp/dicstrain.rst

This file was deleted.

docs/source/cpp/dicutil.rst

This file was deleted.

docs/source/examples/examples.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -10,7 +10,7 @@ Sensor Simulation Basics @@
        examples_basics_sensorsim
-    Digital Image Correlation
+    DIC & Strain Calculations
     -------------------------
     .. toctree::
        :maxdepth: 2
@@ Expand Down @@

docs/source/examples/examples_dic.rst

-Original file line number
+Diff line change
@@ -1,6 +1,6 @@
     .. _examples_dic:
-    Digital Image Correlation (DIC)
+    DIC & Strain Calculations
     ================================
     .. toctree::
@@ Expand All / @@ -11,4 +11,5 @@ Digital Image Correlation (DIC) @@
        dic/ex3_plate_with_hole_strain.rst
        dic/ex4_dic_blender.rst
        dic/ex5_dic_challenge.rst
+       dic/ex6_hrdic.rst

docs/source/guide/guide_blender.rst

This file was deleted.

docs/source/guide/guide_dic.rst

This file was deleted.

0 docs/source/dev_guide/dev_guide.rst → docs/source/guide_dev/dev_guide.rst

File renamed without changes.

0 ...rce/dev_guide/dev_guide_customsensors.rst → ...rce/guide_dev/dev_guide_customsensors.rst

File renamed without changes.

0 ...source/dev_guide/dev_guide_designspec.rst → ...source/guide_dev/dev_guide_designspec.rst

File renamed without changes.

0 docs/source/dev_guide/dev_guide_python.rst → docs/source/guide_dev/dev_guide_python.rst

File renamed without changes.

docs/source/guide_theory/guide_theory.rst

-Original file line number
+Diff line change
@@ -0,0 +1,14 @@
+    .. _guide_theory:
+    Theory Guide
+    =================================
+    Module user guides
+    ------------------
+    .. toctree::
+       :maxdepth: 1
+       guide_theory_dic.rst

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc Improvements #243

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!