From cca372de0e65c2ab2bef248c940ba1bd94763c3b Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Wed, 18 Oct 2023 14:02:19 -0400 Subject: [PATCH] Set up sphinx-gallery --- .github/workflows/docs.yml | 2 +- .github/workflows/main.yml | 2 +- .gitignore | 2 ++ docs/Makefile | 11 ++++++++++- docs/conf.py | 18 +++++++++++++++--- docs/examples.rst | 6 ------ docs/index.rst | 2 +- docs/requirements.txt | 2 +- examples/README.rst | 3 +++ examples/convolution_2d.py | 27 ++++++++++++++------------- 10 files changed, 48 insertions(+), 27 deletions(-) delete mode 100644 docs/examples.rst create mode 100644 examples/README.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7fc43cb..c5a6d3e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -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: | diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index fdc3ce2..b880acd 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 957cfc9..5b91a28 100644 --- a/.gitignore +++ b/.gitignore @@ -619,3 +619,5 @@ MigrationBackup/ poetry.lock devNBs/ + +docs/examples/ diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..c95d4c0 100644 --- a/docs/Makefile +++ b/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). diff --git a/docs/conf.py b/docs/conf.py index 14e7b24..a56c66c 100644 --- a/docs/conf.py +++ b/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, +} diff --git a/docs/examples.rst b/docs/examples.rst deleted file mode 100644 index 8dd0632..0000000 --- a/docs/examples.rst +++ /dev/null @@ -1,6 +0,0 @@ - -Examples -======== - - -This page is currently unpopulated. diff --git a/docs/index.rst b/docs/index.rst index f83aabf..2b44b9e 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index 06c013f..0e3d6ec 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,6 @@ sphinx -nbsphinx sphinx_copybutton sphinx-gallery +matplotlib pydata-sphinx-theme texext diff --git a/examples/README.rst b/examples/README.rst new file mode 100644 index 0000000..a3ea4f1 --- /dev/null +++ b/examples/README.rst @@ -0,0 +1,3 @@ + +Examples +======== diff --git a/examples/convolution_2d.py b/examples/convolution_2d.py index efc29fb..d746c5b 100644 --- a/examples/convolution_2d.py +++ b/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)