[maint] docs cleanup (#18)

* Rename example_gallery to examples

* Clean up some docs

* Add docs links

* Add README to docs

---------

Co-authored-by: Charles Guan <3221512+charlesincharge@users.noreply.github.com>

Author: charlesbmi

README.md

@@ -51,12 +51,12 @@ Build prerequisites:
 
 ## Examples
 
-Try our examples:
+Try our [examples](https://forest-neurotech.github.io/mach/examples/):
 
 * [📊 Plane Wave Imaging with PICMUS Dataset](examples/plane_wave_compound.py)
 * [🩸 Doppler Imaging](examples/doppler.py)
 
-If you don't have a CUDA-enabled GPU, you can download the notebook from the docs and open in Google Colab (select a GPU instance).
+If you don't have a CUDA-enabled GPU, you can download the notebook from the [docs](https://forest-neurotech.github.io/mach/examples/) and open in Google Colab (select a GPU instance).
 
 ## Contributing
 

docs/.gitignore

@@ -1,4 +1,4 @@
-example_gallery/
+examples/
 gen_modules/
 generated/
 _build/

docs/conf.py

@@ -41,10 +41,14 @@
     "sphinx_gallery.gen_gallery",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
+    "myst_parser",
 ]
 
 autosummary_generate = True
 
+# Source file suffixes
+source_suffix = [".rst", ".md"]
+
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ["_templates"]
 
@@ -71,7 +75,7 @@
     # path to your example scripts
     "examples_dirs": ["../examples"],
     # path to where to save gallery generated output
-    "gallery_dirs": ["example_gallery"],
+    "gallery_dirs": ["examples"],
     # execute ALL examples/*.py files
     "filename_pattern": "/*",
     # specify that examples should be ordered according to filename

docs/index.rst

@@ -1,17 +1,21 @@
 mach
 ==============================================================
 
-This documentation is under construction. For now, it mostly just includes the gallery of examples.
+.. note::
+
+   🚧 This documentation is under construction.
+
+**mach** is an ultrafast CUDA-accelerated ultrasound beamformer for Python users, developed at Forest Neurotech.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Gallery:
+   :caption: README:
 
-   example_gallery/index
+   readme
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples:
+n
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   examples/index

examples/README.rst

@@ -1,9 +1,8 @@
-Examples Gallery
+Gallery
 ================
 
 This directory contains tutorial examples demonstrating mach capabilities.
-Each example is designed to work with sphinx-gallery for automatic documentation generation
-and can also be converted to Jupyter notebooks.
+Each example is designed to work with sphinx-gallery for automatic documentation generation.
 
 Available Examples
 ------------------
@@ -14,47 +13,15 @@ Available Examples
 - **plane_wave_compound.py**: Plane wave compounding with PICMUS challenge data.
   Demonstrates coherent compounding of multiple plane wave angles for improved image quality.
 
-Sphinx-Gallery Integration
---------------------------
-
-These examples follow sphinx-gallery conventions:
-
-- Docstring with reStructuredText formatting for the main description
-- ``# %%`` comments to separate code cells
-- Proper attribution to external datasets and references
-- Educational narrative with clear learning objectives
-
-To build the documentation with sphinx-gallery::
-
-    make docs
-
-Jupyter Notebook Conversion
----------------------------
-
-To convert any example to a Jupyter notebook::
-
-    pip install jupytext
-    jupytext --to notebook examples/*.py
-
 Dependencies
 ------------
 
-**Common dependencies:**
-- **matplotlib**: Required for all visualizations
-- **numpy**: Basic array operations
-- **einops**: Required for array reshaping operations
-
-**Example-specific dependencies:**
-
-For **doppler.py**:
-- **pymust**: Required for PyMUST data loading and RF-to-IQ conversion
+**Additional common dependencies:**
 
-For **plane_wave_compound.py**:
-- **pyuff-ustb**: Required for UFF data loading (``pip install pyuff-ustb``)
+- ``matplotlib``: Required for visualizations
+- ``numpy``: Basic array operations
 
-Attribution
------------
+**Example-specific dependencies:**
 
-- **PyMUST/MUST**: Garcia, D. MUST: An Open Platform for Ultrasound Research. https://www.biomecardio.com/MUST/index.html
-- **PICMUS** Liebgott, H. et al. Plane-Wave Imaging Challenge in Medical Ultrasound. https://www.creatis.insa-lyon.fr/Challenge/IEEE_IUS_2016/
-- **Inspired by**: ultraspy tutorials (https://ultraspy.readthedocs.io/) and vbeam examples (https://github.com/magnusdk/vbeam/)
+- **doppler.py** requires ``pymust`` to load example data and demodulate RF to IQ (``pip install pymust``)
+- **plane_wave_compound.py** requires ``pyuff-ustb`` to load example data (``pip install pyuff-ustb``)

examples/plane_wave_compound.py

@@ -12,6 +12,11 @@
 - Beamform data from multiple plane-wave transmits
 - Coherently compound the results
 - Visualize the results
+
+Attribution:
+
+- Example inspired by vbeam examples (https://github.com/magnusdk/vbeam/)
+- Dataset from PICMUS challenge (https://www.creatis.insa-lyon.fr/Challenge/IEEE_IUS_2016/)
 """
 
 # %%

pyproject.toml

@@ -100,8 +100,10 @@ compare = [
     "cupy-cuda12x>=12.0.0",
 ]
 docs = [
-    # includes example-dependencies
     "ipykernel>=6.10",
+    "matplotlib>=3.9.4",
+    "myst-parser>=3.0.1",
+    "numpy>=2.0.2",
     "sphinx>=7.2.6",
     "sphinx-book-theme>=1.1.3",
     "sphinx-gallery>=0.18.0",