waltsims · waltsims · Sep 11, 2025 · Aug 3, 2025 · Aug 3, 2025 · Aug 3, 2025
diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml
@@ -0,0 +1,37 @@
+name: Markdown Link Validator
+
+on:
+  pull_request:
+  push:
+    branches: [ main, master ]
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Check links with lychee
+        # See https://github.com/lycheeverse/lychee-action
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Check all markdown and reStructuredText files
+          args: >-
+            --verbose
+            --no-progress
+            --max-concurrency 12
+            --max-retries 3
+            --retry-wait-time 4
+            --accept 200,206,403,429
+            --exclude-path "docs/get_started/legacy_licenses/gpl-3.0.rst"
+            "**/*.md" "**/*.rst"
+          # Fail the build on any broken link
+          fail: true
+        env:
+          # Exclude localhost and badges
+          LY_CHEE_EXCLUDE: "http://localhost,https://localhost,https://127.0.0.1,https://img.shields.io"
diff --git a/docs/README.md b/docs/README.md
@@ -1,6 +1,6 @@
-# k-Wave-python
+# k-wave-python
 
-[![Support](https://dcbadge.vercel.app/api/server/Yq5Qj6D9vN?style=flat)](https://discord.gg/Yq5Qj6D9vN)
+[![Support](https://img.shields.io/discord/1234942672418897960?style=flat&logo=discord)](https://discord.gg/your-invite-code)
 [![Documentation Status](https://readthedocs.org/projects/k-wave-python/badge/?version=latest)](https://k-wave-python.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/waltsims/k-wave-python/graph/badge.svg?token=6ofwtPiDNG)](https://codecov.io/gh/waltsims/k-wave-python)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/waltsims/k-wave-python/master)
@@ -19,7 +19,7 @@ to leverage pythonic practices.
 
 ![](_static/example_bmode.png)
 
-A large [collection of examples](../examples/) exists to get started with k-wave-python. All examples can be run in Google Colab notebooks with a few clicks. One can begin with e.g. the [B-mode reconstruction example notebook](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
+A large [collection of examples](../examples/) exists to get started with k-wave-python. All examples can be run in Google Colab notebooks with a few clicks. One can begin with e.g. the [B-mode reconstruction example notebook](https://colab.research.google.com/github/waltsims/k-wave-python/blob/HEAD/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
 
 This example file steps through the process of:
  1. Generating a simulation medium

diff --git a/docs/conf.py b/docs/conf.py
@@ -23,8 +23,46 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_mdinclude",
+    "sphinx.ext.extlinks",  # Enables :ghfile: external links
 ]
 
+# Provide a simple GitHub branch/sha fallback for linking to example files.
+# Priority: explicit override via _GITHUB_BRANCH →
+#           READTHEDOCS_GIT_IDENTIFIER (commit) →
+#           READTHEDOCS_GIT_BRANCH / GITHUB_REF_NAME →
+#           "master".
+import os
+
+
+def _detect_current_branch() -> str:
+    """Return a branch/commit identifier for GitHub links with minimal logic.
+
+    Order: _GITHUB_BRANCH override → READTHEDOCS_GIT_IDENTIFIER (commit) →
+    READTHEDOCS_GIT_BRANCH / GITHUB_REF_NAME → "master".
+    """
+    return (
+        os.getenv("_GITHUB_BRANCH")
+        or os.getenv("READTHEDOCS_GIT_IDENTIFIER")
+        or os.getenv("READTHEDOCS_GIT_BRANCH")
+        or os.getenv("GITHUB_REF_NAME")
+        or "master"
+    )
+
+
+_GITHUB_BRANCH = _detect_current_branch()
+
+# Define an extlink so we can write :ghfile:`examples/foo.py` in .rst/.md
+extlinks = {
+    "ghfile": (
+        f"https://github.com/waltsims/k-wave-python/blob/{_GITHUB_BRANCH}/%s",
+        "%s",  # pass-through caption
+    ),
+    "ghdir": (
+        f"https://github.com/waltsims/k-wave-python/tree/{_GITHUB_BRANCH}/%s",
+        "%s",
+    ),
+}
+
 source_suffix = [".rst", ".md"]
-source_suffix = [".rst", ".md"]
+extensions = [
+    "sphinx.ext.extlinks",  # Enables :ghfile: external links
+    "myst_parser",          # Enables Markdown sources
+]
+
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
-source_suffix = [".rst", ".md"]
+extensions = [
+    "sphinx.ext.extlinks",  # Enables :ghfile: external links
+    "myst_parser",          # Enables Markdown sources
+]
+
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 templates_path = ["_templates"]
 exclude_patterns = ["README.md", "_build", "Thumbs.db", ".DS_Store"]
@@ -36,9 +74,10 @@
 html_theme = "furo"
 html_theme_options = {
     "source_repository": "https://github.com/waltsims/k-wave-python",
-    "source_branch": "master",
+    "source_branch": _GITHUB_BRANCH,
     "source_directory": "docs/",
 }
+
 html_static_path = ["_static"]
 
 # -- Options for todo extension ----------------------------------------------

diff --git a/docs/examples_guide.rst b/docs/examples_guide.rst
@@ -0,0 +1,179 @@
+Examples: k-Wave-Python Step-by-Step
+=======================
+
+The k-Wave Python examples are organized to help you progress from basic wave physics to advanced applications. Each example demonstrates the four-component framework (Grid, Medium, Source, Sensor) with increasing complexity.
+
+Start with the :doc:`get_started/first_simulation` tutorial, then follow this suggested learning path:
+
+Basic Wave Propagation (IVP - Initial Value Problems)
+-----------------------------------------------------
+
+**Start Here**: Learn fundamental wave physics using initial pressure distributions (the simplest source type).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 40 20
+
+   * - Example
+     - Core Concept
+     - Topics
+   * - :ghdir:`examples/ivp_photoacoustic_waveforms/`
+     - 2D vs 3D wave propagation physics
+     - **IVP** • Wave spreading • Compact support
+
+Simple Transducers & Sources
+-----------------------------
+
+**Next Step**: Introduction to time-varying sources and practical transducer modeling.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 40 20
+
+   * - Example
+     - Core Concept
+     - Topics
+   * - :ghdir:`examples/us_defining_transducer/`
+     - Basic ultrasound transducer setup
+     - **US** • Transducer basics • Time-varying sources
+   * - :ghdir:`examples/at_circular_piston_3D/`
+     - Simple focused geometry
+     - **AT** • 3D focusing • Geometric sources
+   * - :ghdir:`examples/at_circular_piston_AS/`
+     - Computational efficiency with symmetry
+     - **AT** • Axisymmetric • Computational optimization
+
+Medical Imaging Applications
+----------------------------
+
+**Practical Applications**: See how basic concepts combine into real-world medical imaging systems.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 40 20
+
+   * - Example
+     - Application
+     - Topics
+   * - :ghdir:`examples/us_beam_patterns/`
+     - Understanding acoustic beam formation
+     - **US** • Beam focusing • Field patterns
+   * - :ghdir:`examples/us_bmode_linear_transducer/`
+     - Complete ultrasound imaging pipeline
+     - **US** • Medical imaging • Signal processing
+   * - :ghdir:`examples/pr_2D_FFT_line_sensor/`
+     - Photoacoustic image reconstruction
+     - **PR** • Image reconstruction • FFT methods
+   * - :ghdir:`examples/pr_2D_TR_line_sensor/`
+     - Alternative reconstruction approach
+     - **PR** • Time reversal • Reconstruction
+
+Advanced Transducer Modeling (AT - Array Transducers)
+-----------------------------------------------------
+
+**Complex Geometries**: Learn sophisticated techniques for modeling complex transducer arrays using Cartesian space methods.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 40 20
+
+   * - Example
+     - Advanced Technique
+     - Topics
+   * - :ghdir:`examples/at_array_as_source/`
+     - kWaveArray for complex geometries
+     - **AT** • Array modeling • Anti-aliasing
+   * - :ghdir:`examples/at_array_as_sensor/`
+     - Complex sensor array geometries
+     - **AT** • Sensor arrays • Flexible positioning
+   * - :ghdir:`examples/at_linear_array_transducer/`
+     - Multi-element linear arrays
+     - **AT** • Linear arrays • Element spacing
+   * - :ghdir:`examples/at_focused_bowl_3D/`
+     - 3D focused ultrasound therapy
+     - **AT** • Therapeutic US • 3D focusing
+   * - :ghdir:`examples/at_focused_annular_array_3D/`
+     - Multi-element focused systems
+     - **AT** • Annular arrays • Complex focusing
+
+Advanced Imaging & Reconstruction (PR - Pressure/Photoacoustic Reconstruction)
+-------------------------------------------------------------------------------
+
+**3D Reconstruction**: Advanced reconstruction techniques for photoacoustic and pressure field imaging.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 40 20
+
+   * - Example
+     - Reconstruction Method
+     - Topics
+   * - :ghdir:`examples/pr_3D_FFT_planar_sensor/`
+     - 3D FFT-based reconstruction
+     - **PR** • 3D imaging • Planar arrays
+   * - :ghdir:`examples/pr_3D_TR_planar_sensor/`
+     - 3D time reversal reconstruction
+     - **PR** • 3D time reversal • Volumetric imaging
+   * - :ghdir:`examples/us_bmode_phased_array/`
+     - Advanced ultrasound beamforming
+     - **US** • Phased arrays • Electronic steering
+
+Sensor Physics & Directivity (SD - Sensor Directivity)
+------------------------------------------------------
+
+**Sensor Modeling**: Understanding how sensor size, shape, and directivity affect measurements.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 40 20
+
+   * - Example
+     - Physics Concept
+     - Topics
+   * - :ghdir:`examples/sd_directivity_modelling_2D/`
+     - How sensor size affects measurements
+     - **SD** • Directivity • Finite sensor size
+   * - :ghdir:`examples/sd_focussed_detector_2D/`
+     - Directional sensor sensitivity
+     - **SD** • Focused detection • Sensor design
+   * - :ghdir:`examples/sd_focussed_detector_3D/`
+     - 3D focused sensor modeling
+     - **SD** • 3D detection • Sensor focusing
+
+Computational Optimization (NA - Numerical Analysis)
+----------------------------------------------------
+
+**Advanced Numerics**: Optimize simulations and understand computational aspects.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 40 20
+
+   * - Example
+     - Optimization Topic
+     - Topics
+   * - :ghdir:`examples/na_controlling_the_pml/`
+     - Boundary conditions and efficiency
+     - **NA** • PML boundaries • Computational domains
+
+Understanding the Prefixes
+--------------------------
+
+- **IVP** = Initial Value Problems (wave propagation from initial pressure)
+- **US** = Ultrasound (medical and therapeutic ultrasound applications)  
+- **AT** = Array Transducers (complex geometries using Cartesian space methods)
+- **PR** = Pressure/Photoacoustic Reconstruction (image reconstruction techniques)
+- **SD** = Sensor Directivity (sensor physics and measurement effects)
+- **NA** = Numerical Analysis (computational optimization and methods)
+
+Learning Strategy
+-----------------
+
+1. **Start with IVP**: Understand basic wave physics
+2. **Move to simple US/AT**: Learn transducer basics
+3. **Apply to imaging**: See concepts in real applications (US, PR)
+4. **Master advanced AT**: Handle complex geometries
+5. **Understand sensors**: Learn about measurement physics (SD)
+6. **Optimize**: Improve computational efficiency (NA)
+
+Each example builds on the four-component framework, but with increasing sophistication in how the components are configured and used.