sphinx gallery

docs/source/conf.py

@@ -2,7 +2,22 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# Force offscreen rendering
+import os
+
+os.environ["WGPU_FORCE_OFFSCREEN"] = "1"
+
 import fastplotlib
+from pygfx.utils.gallery_scraper import find_examples_for_gallery
+from pathlib import Path
+import sys
+from sphinx_gallery.sorting import ExplicitOrder
+
+ROOT_DIR = Path(__file__).parents[1].parents[0]  # repo root
+EXAMPLES_DIR = ROOT_DIR / "examples" / "desktop"
+
+sys.path.insert(0, str(ROOT_DIR))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -24,8 +39,31 @@
     "sphinx_copybutton",
     "sphinx_design",
     "nbsphinx",
+    "sphinx_gallery.gen_gallery"
 ]
 
+sphinx_gallery_conf = {
+    "gallery_dirs": "_gallery",
+    "backreferences_dir": "_gallery/backreferences",
+    "doc_module": ("fastplotlib",),
+    "image_scrapers": ("pygfx",),
+    "remove_config_comments": True,
+    "subsection_order": ExplicitOrder(
+        [
+            "../../examples/desktop/image",
+            "../../examples/desktop/gridplot",
+            "../../examples/desktop/line",
+            "../../examples/desktop/line_collection",
+            "../../examples/desktop/scatter",
+            "../../examples/desktop/heatmap"
+        ]
+    ),
+    "ignore_pattern": r'__init__\.py',
+}
+
+extra_conf = find_examples_for_gallery(EXAMPLES_DIR)
+sphinx_gallery_conf.update(extra_conf)
+
 autosummary_generate = True
 
 templates_path = ["_templates"]
@@ -52,7 +90,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
-    "pygfx": ("https://pygfx.readthedocs.io/en/latest", None),
+    "pygfx": ("https://pygfx.com/stable/", None),
     "wgpu": ("https://wgpu-py.readthedocs.io/en/latest", None),
 }
 

docs/source/index.rst

@@ -26,6 +26,12 @@ Welcome to fastplotlib's documentation!
    Utils <api/utils>
    GPU <api/gpu>
 
+.. toctree::
+   :caption: Gallery
+   :maxdepth:  2
+
+   Gallery <_gallery/index>
+
 Summary
 =======
 

docs/source/quickstart.ipynb

@@ -48,6 +48,18 @@
     "import imageio.v3 as iio"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "46a9a80b-0481-4788-975b-4ff364a03033",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "### For the purpose of rendering our documentation, we need to manually make sure that offscreen rendering is not being used!\n",
+    "import os\n",
+    "os.environ[\"WGPU_FORCE_OFFSCREEN\"] = \"false\""
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -1665,7 +1677,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.3"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

examples/README.rst

@@ -0,0 +1,2 @@
+Examples that use fastplotlib
+=============================

examples/desktop/gridplot/README.rst

@@ -0,0 +1,2 @@
+GridPlot Examples
+=================

examples/desktop/gridplot/gridplot.py

@@ -5,11 +5,11 @@
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
 fig = fpl.Figure(shape=(2, 2))
 
 im = iio.imread("imageio:clock.png")
@@ -22,6 +22,9 @@
 fig[1, 0].add_image(data=im3)
 fig[1, 1].add_image(data=im4)
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = fig.canvas
+
 fig.show()
 
 fig.canvas.set_logical_size(800, 800)

examples/desktop/gridplot/gridplot_non_square.py

@@ -5,11 +5,11 @@
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
 fig = fpl.Figure(shape=(2, 2), controller_ids="sync")
 
 im = iio.imread("imageio:clock.png")
@@ -22,6 +22,9 @@
 
 fig.show()
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = fig.canvas
+
 fig.canvas.set_logical_size(800, 800)
 
 for subplot in fig:

examples/desktop/heatmap/README.rst

@@ -0,0 +1,2 @@
+Heatmap Examples
+================

examples/desktop/heatmap/heatmap.py

@@ -5,12 +5,15 @@
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import numpy as np
+from wgpu.gui.offscreen import WgpuCanvas
 
+canvas = WgpuCanvas()
 
-fig = fpl.Figure()
+fig = fpl.Figure(canvas=canvas)
 
 xs = np.linspace(0, 1_000, 10_000)
 

examples/desktop/heatmap/heatmap_cmap.py

@@ -5,12 +5,15 @@
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import numpy as np
+from wgpu.gui.offscreen import WgpuCanvas
 
+canvas = WgpuCanvas()
 
-fig = fpl.Figure()
+fig = fpl.Figure(canvas=canvas)
 
 xs = np.linspace(0, 1_000, 10_000)
 

examples/desktop/heatmap/heatmap_data.py

@@ -5,12 +5,15 @@
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'hidden'
 
 import fastplotlib as fpl
 import numpy as np
+from wgpu.gui.offscreen import WgpuCanvas
 
+canvas = WgpuCanvas()
 
-fig = fpl.Figure()
+fig = fpl.Figure(canvas=canvas)
 
 xs = np.linspace(0, 1_000, 10_000)
 

examples/desktop/heatmap/heatmap_vmin_vmax.py

@@ -5,12 +5,15 @@
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import numpy as np
+from wgpu.gui.offscreen import WgpuCanvas
 
+canvas = WgpuCanvas()
 
-fig = fpl.Figure()
+fig = fpl.Figure(canvas=canvas)
 
 xs = np.linspace(0, 1_000, 10_000)
 

examples/desktop/image/README.rst

@@ -0,0 +1,2 @@
+Image Examples
+==============

examples/desktop/image/image_cmap.py

@@ -1,10 +1,12 @@
 """
-Simple Plot
-============
+Image colormap
+==============
+
 Example showing simple plot creation and subsequent cmap change with Standard image from imageio.
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
@@ -18,6 +20,9 @@
 
 fig.show()
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = fig.canvas
+
 fig.canvas.set_logical_size(800, 800)
 
 fig[0, 0].auto_scale()

examples/desktop/image/image_rgb.py

@@ -1,15 +1,16 @@
 """
-Simple Plot
-============
+RGB Image
+=========
+
 Example showing the simple plot creation with 512 x 512 2D RGB image.
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
 im = iio.imread("imageio:astronaut.png")
 
 fig = fpl.Figure()
@@ -19,6 +20,9 @@
 
 fig.show()
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = fig.canvas
+
 fig.canvas.set_logical_size(800, 800)
 
 fig[0, 0].auto_scale()

examples/desktop/image/image_rgbvminvmax.py

@@ -1,15 +1,16 @@
 """
-Simple Plot
-============
+RGB Image Vmin/Vmax
+===================
+
 Example showing the simple plot followed by changing the vmin/vmax with 512 x 512 2D RGB image.
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
 im = iio.imread("imageio:astronaut.png")
 
 fig = fpl.Figure()
@@ -19,6 +20,9 @@
 
 fig.show()
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = fig.canvas
+
 fig.canvas.set_logical_size(800, 800)
 
 fig[0, 0].auto_scale()

examples/desktop/image/image_simple.py

@@ -1,15 +1,16 @@
 """
-Simple Plot
+Simple Image
 ============
+
 Example showing the simple plot creation with Standard imageio image.
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
 fig = fpl.Figure()
 
 data = iio.imread("imageio:camera.png")
@@ -19,6 +20,9 @@
 
 fig.show()
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = fig.canvas
+
 fig.canvas.set_logical_size(800, 800)
 
 fig[0, 0].auto_scale()

examples/desktop/image/image_vminvmax.py

@@ -1,15 +1,16 @@
 """
-Simple Plot
-============
+Image Vmin/Vmax
+===============
+
 Example showing the simple plot creation followed by changing the vmin/vmax with Standard imageio image.
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
 fig = fpl.Figure()
 
 data = iio.imread("imageio:astronaut.png")
@@ -19,6 +20,9 @@
 
 fig.show()
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = fig.canvas
+
 fig.canvas.set_logical_size(800, 800)
 
 fig[0, 0].auto_scale()

examples/desktop/image/image_widget.py

@@ -1,18 +1,23 @@
 """
 Image widget
 ============
+
 Example showing the image widget in action.
 When run in a notebook, or with the Qt GUI backend, sliders are also shown.
 """
 
+# sphinx_gallery_pygfx_docs = 'hidden'
+
 import fastplotlib as fpl
 import imageio.v3 as iio  # not a fastplotlib dependency, only used for examples
 
-
 a = iio.imread("imageio:camera.png")
 iw = fpl.ImageWidget(data=a, cmap="viridis")
 iw.show()
 
+# set canvas variable for sphinx_gallery to properly generate examples
+canvas = iw.figure.canvas
+
 
 if __name__ == "__main__":
     print(__doc__)