diff --git a/doc/conf.py b/doc/conf.py index bcf8768f3d70eef6790f997f2531f19d399537b6..07e4fa8570be890a47cc1590d71309e4a33b209e 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 0000000000000000000000000000000000000000..4bc50639c7cee7546f9eb801a8178eb458e637ae --- /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 8775752b324ee822a251f68a109cc3a479843d1a..152d2fdd3b94959670b0e77d996b87d4abd0d3f5 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 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/examples/README.rst b/examples/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..0f74ff34111a108f3f1841fa97a90814a5dbfaa3 --- /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 0000000000000000000000000000000000000000..fdc9f4fc85b40d124206e800cc819a212eaecd81 --- /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 16d4db6b94616ec897f86e545af7690d226bcec3..539b463d5a3f61d2edfa8a22e005d3073f7476c1 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,3 +1,4 @@ +memory_profiler numpydoc pytest pytest-cov