DOC: Restructure "examples" page

* Add symbolic link `examples/` that points to `doc/examples` * Move `.rst` files out of examples directory * Short explanation of Binder links * Python example scripts get their own sub-page (instead of cluttering the main example page)
sfstoolbox · Feb 27, 2019 · 301c2d6 · 301c2d6
1 parent a4c7c8c
commit 301c2d6
Show file tree

Hide file tree

Showing 7 changed files with 33 additions and 29 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -39,7 +39,6 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',  # support for NumPy-style docstrings
     'sphinx.ext.intersphinx',
-    'sphinx.ext.extlinks',
     'sphinxcontrib.bibtex',
     'matplotlib.sphinxext.plot_directive',
     'nbsphinx',
@@ -113,10 +112,6 @@
 except Exception:
     release = '<unknown>'
 
-binder_base_url = 'https://mybinder.org/v2/gh/sfstoolbox/sfs-python/'
-
-extlinks = {'binder': (binder_base_url + release + '?filepath=%s', 'binder:')}
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None

diff --git a/doc/example-python-scripts.rst b/doc/example-python-scripts.rst
@@ -0,0 +1,11 @@
+Example Python Scripts
+======================
+
+Various example scripts are located in the directory ``doc/examples/``, e.g.
+
+* :download:`examples/sound_field_synthesis.py`:  Illustrates the general usage
+  of the toolbox
+* :download:`examples/horizontal_plane_arrays.py`:  Computes the sound fields
+  for various techniques, virtual sources and loudspeaker array configurations
+* :download:`examples/soundfigures.py`:  Illustrates the synthesis of sound
+  figures with Wave Field Synthesis
diff --git a/doc/examples.rst b/doc/examples.rst
@@ -0,0 +1,18 @@
+Examples
+========
+
+.. only:: html
+
+    You can play with the Jupyter notebooks (without having to install anything)
+    by clicking |binder logo| on the respective example page.
+
+    .. |binder logo| image:: https://mybinder.org/badge_logo.svg
+        :target: https://mybinder.org/v2/gh/sfstoolbox/sfs-python/master?
+                 filepath=doc/examples
+
+.. toctree::
+    :maxdepth: 1
+
+    examples/modal-room-acoustics
+    examples/mirror-image-source-model
+    example-python-scripts
diff --git a/doc/examples/index.rst b/doc/examples/index.rst
diff --git a/doc/examples/ipython_kernel_config.py b/doc/examples/ipython_kernel_config.py
@@ -1,3 +1,5 @@
+# This is a configuration file that's used when opening the Jupyter notebooks
+# in this directory.
 # See https://nbviewer.jupyter.org/github/mgeier/python-audio/blob/master/plotting/matplotlib-inline-defaults.ipynb
 
 c.InlineBackend.figure_formats = {'svg'}

diff --git a/doc/index.rst b/doc/index.rst
@@ -5,7 +5,7 @@
 .. toctree::
 
     installation
-    examples/index
+    examples
     api
     references
     contributing

diff --git a/examples b/examples
@@ -0,0 +1 @@
+doc/examples/