Merge pull request #92 from flatironinstitute/docs/sphinx-gallery

Set up sphinx-gallery

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Build Pytorch-FINUFFT docs
+name: docs
 
 on:
   push:
@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  build-docs:
+  build:
     runs-on: ubuntu-latest
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
@@ -26,7 +26,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip wheel
           python -m pip install --upgrade -r docs/requirements.txt
-          python -m pip install --no-deps .
+          python -m pip install .
 
       - name: Build docs
         run: |

.github/workflows/main.yml

@@ -84,7 +84,7 @@ jobs:
 
     - name: Check docs
       env:
-        SPHINXOPTS: "-Wq --keep-going"
+        SPHINXOPTS: "-Wq --keep-going -D plot_gallery=0"
       run: |
         cd docs/
         make clean

.gitignore

@@ -619,3 +619,5 @@ MigrationBackup/
 
 poetry.lock
 devNBs/
+
+docs/examples/

docs/Makefile

@@ -12,7 +12,16 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+clean:
+	$(RM) -rf $(BUILDDIR)/*
+	$(RM) -rf examples/
+
+.PHONY: help Makefile clean
+
+# shortcut to skip building examples, run like:
+# make fast-html
+fast-%: Makefile
+	$(MAKE) $* SPHINXOPTS="$(SPHINXOPTS) -D plot_gallery=0"
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/conf.py

@@ -11,14 +11,13 @@
 
 extensions = [
     "sphinx.ext.autosummary",
-    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx_gallery.gen_gallery",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
-    "sphinx.ext.autodoc",
     "sphinx.ext.githubpages",
     "sphinx.ext.mathjax",
-    "nbsphinx",
     "sphinx_copybutton",
     "texext.math_dollar",
 ]
@@ -75,3 +74,16 @@
 # by removing things like In [10]: from the text to be copied
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
 copybutton_prompt_is_regexp = True
+
+# sphinx-gallery
+sphinx_gallery_conf = {
+    "examples_dirs": "../examples",
+    "gallery_dirs": "examples",
+    "image_scrapers": ("matplotlib",),
+    "filename_pattern": ".*\.py",  # execute all examples
+    "only_warn_on_example_error": True,
+    "reference_url": {
+        "pytorch_finufft": None,  # local docs
+    },
+    "download_all_examples": False,
+}

docs/index.rst

@@ -18,5 +18,5 @@ both values and positions for the :external+finufft:doc:`"type 1" and "type 2" <
    :caption: Contents:
 
    installation
-   examples
+   examples/index
    api

docs/requirements.txt

@@ -1,6 +1,6 @@
 sphinx
-nbsphinx
 sphinx_copybutton
 sphinx-gallery
+matplotlib
 pydata-sphinx-theme
 texext

examples/README.rst

@@ -0,0 +1,3 @@
+
+Examples
+========

examples/convolution_2d.py

@@ -1,6 +1,7 @@
-#######################################################################################
-# Convolution in 2D example
-# =========================
+"""
+Convolution in 2D
+=================
+"""
 
 
 #######################################################################################
@@ -25,7 +26,7 @@ def gaussian_function(x, y, sigma=1):
 
 #######################################################################################
 # Let's visualize this filter kernel. We will be using it to convolve with points
-# living on the [0, 2*pi] x [0, 2*pi] torus. So let's dimension it accordingly.
+# living on the $[0, 2*\pi] \times [0, 2*\pi]$ torus. So let's dimension it accordingly.
 
 shape = (128, 128)
 sigma = 0.5
@@ -35,16 +36,16 @@ def gaussian_function(x, y, sigma=1):
 gaussian_kernel = gaussian_function(x[:, np.newaxis], y, sigma=sigma)
 
 fig, ax = plt.subplots()
-ax.imshow(gaussian_kernel)
+_ = ax.imshow(gaussian_kernel)
 
 #######################################################################################
-# In order for the kernel to not shift the signal, we need to place its mass at 0
+# In order for the kernel to not shift the signal, we need to place its mass at 0.
 # To do this, we ifftshift the kernel
 
 shifted_gaussian_kernel = np.fft.ifftshift(gaussian_kernel)
 
 fig, ax = plt.subplots()
-ax.imshow(shifted_gaussian_kernel)
+_ = ax.imshow(shifted_gaussian_kernel)
 
 
 #######################################################################################
@@ -57,7 +58,8 @@ def gaussian_function(x, y, sigma=1):
 ax.set_xlim(0, 2 * np.pi)
 ax.set_ylim(0, 2 * np.pi)
 ax.set_aspect("equal")
-ax.scatter(points[0], points[1], s=1)
+_ = ax.scatter(points[0], points[1], s=1)
+
 
 #######################################################################################
 # Now we can convolve the point cloud with the filter kernel.
@@ -75,7 +77,7 @@ def gaussian_function(x, y, sigma=1):
 fig, axs = plt.subplots(1, 3)
 axs[0].imshow(fourier_shifted_gaussian_kernel.real)
 axs[1].imshow(fourier_points.real, vmin=-10, vmax=10)
-axs[2].imshow(
+_ = axs[2].imshow(
     (
         fourier_points
         * fourier_shifted_gaussian_kernel
@@ -85,7 +87,6 @@ def gaussian_function(x, y, sigma=1):
     vmax=10,
 )
 
-
 #######################################################################################
 # We now have two possibilities: Invert the Fourier transform on a grid, or on a point
 # cloud. We'll first invert the Fourier transform on a grid in order to be able to
@@ -95,7 +96,7 @@ def gaussian_function(x, y, sigma=1):
 
 fig, ax = plt.subplots()
 ax.imshow(convolved_points.real)
-ax.scatter(
+_ = ax.scatter(
     points[1] / 2 / np.pi * shape[0], points[0] / 2 / np.pi * shape[1], s=2, c="r"
 )
 
@@ -118,7 +119,7 @@ def gaussian_function(x, y, sigma=1):
 
 fig, ax = plt.subplots()
 ax.imshow(convolved_points.real)
-ax.scatter(
+_ = ax.scatter(
     points[1] / 2 / np.pi * shape[0],
     points[0] / 2 / np.pi * shape[1],
     s=10 * convolved_at_points,
@@ -231,4 +232,4 @@ def forward(self, points, values):
         48:80, 48:80
     ]
 )
-fig.colorbar(im, ax=ax)
+_ = fig.colorbar(im, ax=ax)