Improvements on the documentation (#275)

* refactor: separate examples in sub galleries.

* fix: mark raw string for correct backslash use.

* fix: docstring formatting

* fixup! add the readme gallery files.

* fix: formatting and typo

* format: black [docs]

[docs]

* fix: correct path for gif files. [docs]

* fix: update template for minigallery. [docs]

* feat: use environment variable for examples

* fix: example are independent of backend

* fix: minigallery working [docs]

* fix: format

* Add info about documentation build.

* fix: handles warning from sphinx [docs]

* feat: use cufinufft for pytest examples

* fix: format

* [docs] fix: typos and string format

* feat: update finufft and cufinufft to 2.4.0

* fix: defer installation of finufft to next stage

* fix: add squeeze to ensure display of images.

* [docs] build docs with cufinufft

* fmt: black

* fix: gridder with finufft and cufinufft.

* fix examples [docs]

Author: paquiteau

.github/workflows/test-ci.yml

@@ -223,7 +223,7 @@ jobs:
           ${{ env.activate_venv }}
           python -m pip install --upgrade pip
           python -m pip install -e .[extra,test,dev]
-          python -m pip install finufft pooch brainweb-dl torch fastmri
+          python -m pip install pooch brainweb-dl torch fastmri
 
       - name: Install Python deps
         shell: bash
@@ -238,6 +238,7 @@ jobs:
         run: |
           ${{ env.activate_venv }}
           export COVERAGE_FILE=coverage_plots
+          export MRINUFFT_BACKEND=cufinufft
           python -m pytest examples -n=4 --cov --cov-branch --cov-report=term --durations=10
 
       - name: Cache brainweb-dl directory
@@ -352,6 +353,7 @@ jobs:
       - name: Build API documentation
         run: |
           ${{ env.activate_venv }}
+          export MRINUFFT_BACKEND=cufinufft
           python -m sphinx docs docs_build
 
       - name: Display data

CONTRIBUTING.md

@@ -146,6 +146,8 @@ To build the documentation locally, you can run the following commands :
     cd mri-nufft/docs
     # do your changes 
     cd .. 
+    # you can specify a specfic backend to run the example with an environment variable:
+    export MRINUFFT_BACKEND=finufft
     python -m sphinx-build docs docs_build 
     # view the documentation in your browser
     python -m http.server --directory docs_build 8080
@@ -154,6 +156,8 @@ To build the documentation locally, you can run the following commands :
 
 
 ## Styleguides
+### Code
+The code base is formatted with [`black`](https://github.com/psf/black) and style guide is enforced with [`ruff`](https://github.com/astral-sh/ruff). You can run `black .` and `ruff check src` to ensure your changes will pass the [linter-check](https://github.com/mind-inria/.github/workflows/style.yml) CI.
 ### Docstrings 
 We use Numpy style docstrings. You can find more information about them [here](https://numpydoc.readthedocs.io/en/latest/format.html).
 

docs/_templates/autosummary/class.rst

@@ -30,3 +30,8 @@
    {%- endfor %}
    {% endif %}
    {% endblock %}
+
+   .. _sphx_glr_backref_{{fullname}}:
+
+   .. minigallery:: {{fullname}}
+      :add-heading:

docs/_templates/autosummary/function.rst

@@ -4,7 +4,5 @@
 
 .. autofunction:: {{ objname }}
 
-..  _sphx_glr_backref_{{fullname}}:
-
-.. minigallery:: {{fullname}}
-   :add-heading:
+.. minigallery:: {{module}}.{{objname}}
+   :add-heading: Example using ``{{objname}}``:

docs/conf.py

@@ -81,6 +81,7 @@
     "within_subsection_order": "ExampleTitleSortKey",
     "filename_pattern": "/example_",
     "ignore_pattern": r"(__init__|conftest|utils).py",
+    "prefer_full_module": {r".*"},
     "nested_sections": True,
     "binder": {
         "org": "mind-inria",
@@ -100,7 +101,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "cupy": ("https://docs.cupy.dev/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
 }

docs/getting_started.rst

@@ -34,7 +34,7 @@ In order to perform Non-Uniform fast Fourier transform you need to install a spe
 
    Then, use the ``get_operator(backend=<your backend>, ... )`` to initialize your MRI-NUFFT operator.
 
-   For more information , check the :ref:`Examples`
+   For more information , check the :ref:`general_examples`
 
 
 Supported Libraries

docs/mrinufft_convention.rst

@@ -37,7 +37,7 @@ All MRI-NUFFT operators inherit from :class:`FourierOperatorBase` . The minimum
 
 .. tip::
 
-   The precision of the samples array will determine the precision of the computation. See also :ref:`K-Space Trajectories`
+   The precision of the samples array will determine the precision of the computation. See also :ref:`kspace_traj`
 
 Moreover, the two following methods should be implemented for each backend
 
@@ -67,6 +67,7 @@ Adding a NUFFT Backend
 
 Adding a NUFFT backend to MRI-NUFFT should be easy. We recommend to check how other backends have been inplemented. CPU-based nufft interface can use the `FourierOperatorCPU` to minimize the boiler-plate.
 
+.. _kspace_traj:
 
 K-Space Trajectories
 ====================

docs/nufft.rst

@@ -1,5 +1,5 @@
 .. include:: <isonum.txt>
-.. __NUFFT:
+.. _NUFFT:
 ====================
  The NUFFT Operator
 ====================

examples/GPU/example_3d_trajectory_display.py

@@ -11,13 +11,17 @@
 # %%
 
 # Imports
+import os
 from mrinufft.trajectories.display3D import get_gridded_trajectory
 import mrinufft.trajectories.trajectory3D as mtt
 from mrinufft.trajectories.utils import Gammas
 import matplotlib.pyplot as plt
 import numpy as np
 
 
+BACKEND = os.environ.get("MRINUFFT_BACKEND", "gpunufft")
+
+
 # %%
 # Helper function to Displaying 3D Gridded Trajectories
 # =====================================================
@@ -56,6 +60,8 @@ def create_grid(grid_type, trajectories, traj_params, **kwargs):
             traj_params["img_size"],
             grid_type=grid_type,
             traj_params=traj_params,
+            backend=BACKEND,
+            osf=2,
             **kwargs,
         )
         plot_slices(axs[:, i], grid, title=name)

examples/GPU/example_cg.py

@@ -6,7 +6,7 @@
 An example to show how to reconstruct volumes using conjugate gradient method.
 
 This script demonstrates the use of the Conjugate Gradient (CG) method
-for solving systems of linear equations of the form Ax = b, where A is a symmetric
+for solving systems of linear equations of the form :math:`Ax = b`, where :math:`A`` is a symmetric
 positive-definite matrix. The CG method is an iterative algorithm that is particularly
 useful for large, sparse systems where direct methods are computationally expensive.
 
@@ -32,6 +32,9 @@
 from brainweb_dl import get_mri
 from mrinufft.density import voronoi
 from matplotlib import pyplot as plt
+import os
+
+BACKEND = os.environ.get("MRINUFFT_BACKEND", "gpunufft")
 
 # %%
 # Setup Inputs
@@ -41,12 +44,13 @@
 
 # %%
 # Setup the NUFFT operator
-NufftOperator = mrinufft.get_operator("gpunufft")  # get the operator
+NufftOperator = mrinufft.get_operator(BACKEND)  # get the operator
 
 nufft = NufftOperator(
     samples_loc,
     shape=image.shape,
     density=True,
+    squeeze_dims=True,
 )  # create the NUFFT operator
 
 # %%
@@ -74,7 +78,10 @@
 plt.subplot(2, 3, 3)
 plt.title("Adjoint NUFFT")
 plt.imshow(
-    abs(nufft.adj_op(kspace_data)), vmin=image.min(), vmax=image.max(), cmap="gray"
+    abs(nufft.adj_op(kspace_data)),
+    vmin=image.min(),
+    vmax=image.max(),
+    cmap="gray",
 )
 plt.colorbar()