Examples gallery for napari-threedee (#104)

* Move example scripts into docs directory, is a limitation of mkdocs-gallery

* Docstrings with RST headings are required for mkdocs-gallery

* Correct name of plugin widget for example script

* Update gallery readme headings

* Include ALL example script directories in gallery

* Shorter headings that fit in docs sidebar

* Pin mkdocs to 1.2.4 due to mkdocs-gallery issue smarie/mkdocs-gallery#57

* Add issue link as comment, so we know when to remove the pin

* Fix merge conflict

* Run mesh_headlight examples now bug is fixed

* Verbose output of installed packages in CI

* Add napari to dev requirments, we need it to build the examples gallery

* Remember to install a backend for napari

* Use Talley's github action to setup qt properly in remote env

* Use Ashley Anderson's headless GUI action for napari on CI

* Fix .github workflow formatting error

* Try to fix github CI workflow formatting again

* Make docs build strict about any errors

* Prevent filename conflicts with example scripts

* mkdocs-gallery uses recursive search, don't duplicate directories here

* Add link to example gallery from README

.github/workflows/test_and_deploy.yml

@@ -66,6 +66,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
+    - uses: tlambert03/setup-qt-libs@v1
     # Install dependencies
     - name: Set up Python 3.8
       uses: actions/setup-python@v2
@@ -74,10 +75,12 @@ jobs:
     - name: Install dependencies
       run: |
         pip install -r requirements.txt
+        pip list
     # Build the book
     - name: Build the book
-      run: |
-        mkdocs build --strict
+      uses: aganders3/headless-gui@v1
+      with:
+        run: mkdocs build --strict
     # Push the book's HTML to github-pages whenever the main repo branch changes
     - name: GitHub Pages action
       if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}

.gitignore

@@ -62,6 +62,7 @@ docs/_build/
 
 # MkDocs documentation
 /site/
+/docs/generated/
 
 # PyBuilder
 target/

README.md

@@ -34,6 +34,9 @@ To install latest development version :
     pip install git+https://github.com/alisterburt/napari-threedee.git
 
 ## Example applications
+
+See the full list of [example gallery scripts here on our website](https://napari-threedee.github.io/generated/gallery/).
+
 <table border="0">
 <tr><td>
 

docs/examples/README.md

@@ -0,0 +1,3 @@
+# Gallery for napari-threedee
+
+Gallery of examples built with napari-threedee.

examples/empty_surface.py → docs/examples/empty_surface.py

@@ -1,3 +1,10 @@
+"""
+Empty surface
+=============
+
+This example generates sphere mesh data and displays it with napari.
+
+"""
 import napari
 from vispy.geometry import create_sphere
 

docs/examples/library/README.md

@@ -0,0 +1,3 @@
+# Library examples
+
+Examples where napari-threedee is used as a library.

examples/library/camera_spline.py → docs/examples/library/camera_spline_library.py

@@ -1,3 +1,10 @@
+"""
+Camera spline example (library)
+===============================
+
+An example controlling the camera spline,
+using napari-threedee as a library.
+"""
 import napari
 import skimage
 

examples/library/layer_manipulator.py → docs/examples/library/layer_manipulator_library.py

@@ -1,3 +1,10 @@
+"""
+Layer manipulator example (library)
+===================================
+
+An example controlling the layer manipulator,
+using napari-threedee as a library.
+"""
 import napari
 import numpy as np
 

examples/library/mesh_headlight.py → docs/examples/library/mesh_headlight_library.py

@@ -1,3 +1,10 @@
+"""
+Mesh headlight example (library)
+================================
+
+An example controlling the mesh headlight,
+using napari-threedee as a library.
+"""
 import napari
 import numpy as np
 from vispy.io import load_data_file, read_mesh

examples/library/point_annotator.py → docs/examples/library/point_annotator_library.py

@@ -1,3 +1,10 @@
+"""
+Point annotator example (library)
+=================================
+
+An example controlling the point annotator,
+using napari-threedee as a library.
+"""
 from napari_threedee.annotators import PointAnnotator
 
 import napari

examples/library/render_plane_manipulator.py → docs/examples/library/render_plane_manipulator_library.py

@@ -1,3 +1,10 @@
+"""
+Render plane manipulator example (library)
+==========================================
+
+An example controlling the render plane manipulator,
+using napari-threedee as a library.
+"""
 from napari_threedee.manipulators._qt import QtRenderPlaneManipulatorWidget
 
 import napari

examples/library/sphere_annotator.py → docs/examples/library/sphere_annotator_library.py

@@ -1,3 +1,10 @@
+"""
+Sphere annotator example (library)
+==================================
+
+An example controlling the sphere annotator,
+using napari-threedee as a library.
+"""
 from napari_threedee.annotators._qt.qt_sphere_annotator import \
     QtSphereAnnotatorWidget
 

examples/library/spline_annotator.py → docs/examples/library/spline_annotator_library.py

@@ -1,3 +1,10 @@
+"""
+Spline annotator example (library)
+==================================
+
+An example controlling the spline annotator,
+using napari-threedee as a library.
+"""
 import napari
 import skimage
 

examples/library/surface_annotator.py → docs/examples/library/surface_annotator_library.py

@@ -1,3 +1,10 @@
+"""
+Surface annotator example (library)
+===================================
+
+An example controlling the surface annotator,
+using napari-threedee as a library.
+"""
 import napari
 import skimage
 

docs/examples/plugin/README.md

@@ -0,0 +1,3 @@
+# Plugin examples
+
+Examples where napari-threedee is used as a napari plugin.

examples/plugin/camera_spline.py → docs/examples/plugin/camera_spline_plugin.py

@@ -1,3 +1,10 @@
+"""
+Camera spline example (plugin)
+==============================
+
+An example controlling the camera spline,
+using napari-threedee as a napari plugin.
+"""
 import napari
 import skimage
 

examples/plugin/layer_manipulator.py → docs/examples/plugin/layer_manipulator_plugin.py

@@ -1,3 +1,10 @@
+"""
+Layer manipulator example (plugin)
+==================================
+
+An example controlling the layer manipulator,
+using napari-threedee as a napari plugin.
+"""
 import napari
 
 try:

examples/plugin/mesh_headlight.py → docs/examples/plugin/mesh_headlight_plugin.py

@@ -1,3 +1,10 @@
+"""
+Mesh headlight example (plugin)
+===============================
+
+An example controlling the mesh headlight,
+using napari-threedee as a napari plugin.
+"""
 import napari
 import numpy as np
 from vispy.io import load_data_file, read_mesh

examples/plugin/plane_point_annotator.py → docs/examples/plugin/point_annotator_plugin.py

@@ -1,3 +1,10 @@
+"""
+Plane point annotator (plugin)
+==============================
+
+An example controlling the point annotator,
+using napari-threedee as a napari plugin.
+"""
 import napari
 import skimage
 

examples/plugin/points_manipulator.py → docs/examples/plugin/points_manipulator_plugin.py

@@ -1,8 +1,14 @@
-"""Example of using the points manipulator to re-position points.
+"""
+Points manipulator example (plugin)
+===================================
+
+Example of using the points manipulator to re-position points,
+using napari-threedee as a napari plugin.
 
 Enter the point selection mode and click on a point to activate the manipulator.
 Click and drag the arms of the manipulator to move the point.
 When a point is selected, hold space to rotate the view without losing the selection.
+
 """
 
 import numpy as np

examples/plugin/render_plane_manipulator.py → docs/examples/plugin/render_plane_manipulator_plugin.py

@@ -1,3 +1,10 @@
+"""
+Render plane manipulator example (plugin)
+=========================================
+
+An example controlling the render plane manipulator,
+using napari-threedee as a napari plugin.
+"""
 import napari
 from skimage import data
 

examples/plugin/spline_annotator.py → docs/examples/plugin/spline_annotator_plugin.py

@@ -1,3 +1,10 @@
+"""
+Spline annotator example (plugin)
+=================================
+
+An example controlling the spline annotator,
+using napari-threedee as a napari plugin.
+"""
 import napari
 import skimage
 

docs/gallery_conf.py

@@ -0,0 +1,53 @@
+from pathlib import Path
+import warnings
+
+from mkdocs_gallery.scrapers import figure_md_or_html, matplotlib_scraper
+from mkdocs_gallery.gen_data_model import GalleryScript
+import napari
+import qtgallery
+
+warnings.filterwarnings("ignore", category=DeprecationWarning)
+
+
+def napari_image_scraper(block, script: GalleryScript):
+    """Scrape screenshots from napari windows.
+
+    Parameters
+    ----------
+    block : tuple
+        A tuple containing the (label, content, line_number) of the block.
+
+    script : GalleryScript
+        Script being run
+
+    Returns
+    -------
+    md : str
+        The ReSTructuredText that will be rendered to HTML containing
+        the images. This is often produced by :func:`figure_md_or_html`.
+    """
+    viewer = napari.current_viewer()
+    if viewer is not None:
+        image_path = next(script.run_vars.image_path_iterator)
+        screenshot = viewer.screenshot(canvas_only=False, flash=False, path=image_path)
+        viewer.close()
+        return figure_md_or_html([image_path], script)
+    else:
+        return ""
+
+
+def _reset_napari(gallery_conf, file: Path):
+    # Close all open napari windows and reset theme
+    while napari.current_viewer() is not None:
+        napari.current_viewer().close()
+    settings = napari.settings.get_settings()
+    settings.appearance.theme = 'dark'
+    # qtgallery manages the event loop so it
+    # is not completely blocked by napari.run()
+    qtgallery.reset_qapp(gallery_conf, file)
+
+
+conf = {
+    "image_scrapers": [napari_image_scraper, matplotlib_scraper],
+    "reset_modules": [_reset_napari],
+}

mkdocs.yml

@@ -98,6 +98,7 @@ nav:
       - annotations/point_spec.md
       - annotations/sphere_spec.md
       - annotations/spline_spec.md
+  - 'Examples gallery': generated/gallery  # This node will automatically be named and have sub-nodes.
   - 'API':
       - API/napari_utilities.md
       - API/selection_utilities.md
@@ -137,6 +138,13 @@ plugins:
       is_video: True
       video_autoplay: True
       video_loop: True
+  - gallery:
+      conf_script: docs/gallery_conf.py
+      examples_dirs: [docs/examples]
+      gallery_dirs: [docs/generated/gallery]
+      filename_pattern: /*.py  # which scripts will be executed for the docs
+      ignore_pattern: /__init__.py  # ignore these examle files completely
+      run_stale_examples: True
 
 extra_css:
   - stylesheets/extra.css

setup.cfg

@@ -51,12 +51,15 @@ napari.manifest =
 
 [options.extras_require]
 dev = 
-	mkdocs
+	mkdocs==1.2.4 # Pinned due to issue https://github.com/smarie/mkdocs-gallery/issues/57
+	mkdocs-gallery
 	mkdocs-material
 	mkdocstrings[python]
 	mkdocs-video
+	napari[all]
 	pytest
 	pytest-qt
+	qtgallery
 
 [options.package_data]
 napari_threedee = napari.yaml