From b2cf4f3700ab77ff5a686324620e258e3ac87f6c Mon Sep 17 00:00:00 2001
From: Tamas Gal <tgal@km3net.de>
Date: Fri, 29 Nov 2019 11:52:47 +0100
Subject: [PATCH] Add examples gallery
---
doc/conf.py | 11 ++++++++++-
doc/examples.rst | 5 +++++
doc/index.rst | 1 +
doc/modules/generated/.gitkeep | 0
examples/README.rst | 4 ++++
examples/plot_example.py | 29 +++++++++++++++++++++++++++++
requirements-dev.txt | 1 +
7 files changed, 50 insertions(+), 1 deletion(-)
create mode 100644 doc/examples.rst
create mode 100644 doc/modules/generated/.gitkeep
create mode 100644 examples/README.rst
create mode 100644 examples/plot_example.py
diff --git a/doc/conf.py b/doc/conf.py
index bcf8768..07e4fa8 100644
--- a/doc/conf.py
+++ b/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
diff --git a/doc/examples.rst b/doc/examples.rst
new file mode 100644
index 0000000..4bc5063
--- /dev/null
+++ b/doc/examples.rst
@@ -0,0 +1,5 @@
+========
+Examples
+========
+
+.. include:: auto_examples/index.rst
diff --git a/doc/index.rst b/doc/index.rst
index 8775752..152d2fd 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -10,6 +10,7 @@
:maxdepth: 2
:caption: Contents:
+ examples
changelog
autoapi/index
diff --git a/doc/modules/generated/.gitkeep b/doc/modules/generated/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/examples/README.rst b/examples/README.rst
new file mode 100644
index 0000000..0f74ff3
--- /dev/null
+++ b/examples/README.rst
@@ -0,0 +1,4 @@
+Examples to work with km3io
+===========================
+
+Feel free to explore and extend our examples!
diff --git a/examples/plot_example.py b/examples/plot_example.py
new file mode 100644
index 0000000..fdc9f4f
--- /dev/null
+++ b/examples/plot_example.py
@@ -0,0 +1,29 @@
+"""
+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))
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 16d4db6..539b463 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -1,3 +1,4 @@
+memory_profiler
numpydoc
pytest
pytest-cov
--
GitLab