docs: use nbsphix+sphinx-gallery (#299)

widgetti · Mar 30, 2020 · b627a5e · b627a5e
1 parent fad27f9
commit b627a5e
Show file tree

Hide file tree

Showing 21 changed files with 9,087 additions and 13,899 deletions.
diff --git a/docs/source/animation.ipynb b/docs/source/animation.ipynb
diff --git a/docs/source/bokeh.ipynb b/docs/source/bokeh.ipynb
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -40,6 +40,7 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'jupyter_sphinx.embed_widgets',
+    'sphinx_gallery.load_style',
 	'nbsphinx',
 ]
 
@@ -145,12 +146,9 @@
 #html_theme = 'alabaster'
 
 
-try:
-	import sphinx_rtd_theme
-	html_theme = "sphinx_rtd_theme"
-	html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-except:
-	print "rtd theme not found"
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -373,3 +371,15 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None, 'pythreejs': ('https://pythreejs.readthedocs.io/en/latest/', None)}
+
+
+nbsphinx_thumbnails = {
+    'examples/scatter': 'examples/screenshot/scatter.png',
+    'examples/volshow': 'examples/screenshot/volshow-head.png',
+    'examples/mesh': 'examples/screenshot/mesh.png',
+    'examples/animation': 'examples/screenshot/wave.gif',
+    'examples/mcmc': 'examples/screenshot/mcmc.gif',
+    'examples/bqplot': 'examples/screenshot/bqplot.png',
+    'examples/bokeh': 'examples/screenshot/bokeh.png',
+}
+exclude_patterns = ['**.ipynb_checkpoints']
diff --git a/docs/source/example_mcmc.ipynb b/docs/source/example_mcmc.ipynb
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -1,16 +1,19 @@
 Examples
 ========
-.. ipywidgets-setup::
+.. nbgallery::
+   :caption: Examples of using ipyvolume:
 
-   from ipywidgets import VBox, jsdlink, IntSlider, Button
-   import ipyvolume
-   import ipyvolume.pylab as p3
-   import numpy as np
+   examples/scatter
+   examples/volshow
+   examples/mesh
+   examples/animation
+   examples/bqplot
+   examples/bokeh
 
-.. toctree::
-   :maxdepth: 2
-
-   bokeh
-   bqplot
-   example_mcmc
+Feel free to contribute new examples:
 
+  * Add a notebook to `docs/source/examples`
+  * Take a screenshot (of screencapture) and put it at `docs/source/examples/screenshot`.
+  * Make a reference to the screenshot in the notebook, e.g. a markdown cell containing `[screenshot](screenshot/myexample.png)`
+  * Add an entry in `docs/source/conf.py`.
+  * Open a pull request at https://github.com/maartenbreddels/ipyvolume