Add examples gallery

doc/conf.py

@@ -35,7 +35,7 @@ author = 'Zineb Aly, Tamas Gal'
 # ones.
 extensions = [
     'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.viewcode',
-    'autoapi.extension', 'numpydoc'
+    'autoapi.extension', 'numpydoc', 'sphinx_gallery.gen_gallery'
 ]
 autosummary_generate = True
 
@@ -53,6 +53,15 @@ autoapi_dirs = ['../km3io']
 autoapi_options = ['members', 'undoc-members']
 autoapi_include_summaries = True
 
+# Gallery
+sphinx_gallery_conf = {
+    'backreferences_dir': 'modules/generated',
+    'examples_dirs': '../examples',  # path to your example scripts
+    'gallery_dirs':
+    'auto_examples',  # path to where to save gallery generated output
+    'show_memory': True,
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/examples.rst

+========
+Examples
+========
+
+.. include:: auto_examples/index.rst

doc/index.rst

@@ -10,6 +10,7 @@
    :maxdepth: 2
    :caption: Contents:
 
+   examples
    changelog
 
    autoapi/index

examples/README.rst

+Examples to work with km3io
+===========================
+
+Feel free to explore and extend our examples!

examples/plot_example.py

+"""
+This is my example script
+=========================
+
+This example doesn't do much, it just makes a simple output
+"""
+
+#%%
+# This is a section header
+# ------------------------
+# This is the first section!
+# The `#%%` signifies to Sphinx-Gallery that this text should be rendered as
+# rST and if using one of the above IDE/plugin's, also signifies the start of a
+# 'code block'.
+
+# This line won't be rendered as rST because there's a space after the last block.
+myvariable = 2
+print("my variable is {}".format(myvariable))
+# This is the end of the 'code block' (if using an above IDE). All code within
+# this block can be easily executed all at once.
+
+#%%
+# This is another section header
+# ------------------------------
+#
+# In the built documentation, it will be rendered as rST after the code above!
+# This is also another code block.
+
+print('my variable plus 2 is {}'.format(myvariable + 2))

requirements-dev.txt

+memory_profiler
 numpydoc
 pytest
 pytest-cov