docs/conf.py

@@ -33,11 +33,11 @@ author = 'Jan Caron'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.viewcode',
-    'numpydoc'
-]
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.viewcode',
+              'numpydoc',
+              'nbsphinx',
+              'nbsphinx_link']
 
 numpydoc_show_class_members = False
 add_module_names = False
@@ -60,7 +60,7 @@ html_theme = 'sphinx_rtd_theme'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -76,3 +76,7 @@ html_logo = 'EMPyRe Logo.png'
 # the doc.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 html_favicon = 'icon.ico'
+
+# cannot cache unpickable configuration value: 'nbsphinx_custom_formats
+# See https://github.com/sphinx-doc/sphinx/issues/12300
+suppress_warnings = ["config.cache"]

docs/demos.rst

+Demos
+-----
+
+.. toctree::
+    demos/demo1
+    demos/demo2
+    demos/demo3

docs/demos/demo1.nblink

+{
+    "path": "../../demos/demo1_first_steps.ipynb"
+}
\ No newline at end of file

docs/demos/demo2.nblink

+{
+    "path": "../../demos/demo2_handling_3d_fields.ipynb"
+}
\ No newline at end of file

docs/demos/demo3.nblink

+{
+    "path": "../../demos/demo3_io_and_field_manipulation.ipynb"
+}
\ No newline at end of file

docs/fields.rst

@@ -3,6 +3,8 @@ The Field container class
 
 General empyre.fields docu here!
 
+All functions implemented in the subpackages can be accessed directly in the ``empyre.fields`` namespace.
+
 
 The field module
 ----------------

docs/index.rst

@@ -14,6 +14,8 @@ EMPyRe - Electron Microscopy Reconstruction
 
    fields
    vis
+   io
+   demos
 
 
 Indices and tables

docs/io.rst

+The io visualization submodule
+===============================
+
+General empyre.io docu here!
+
+
+The io_field module
+-------------------
+
+.. automodule:: empyre.io.io_field
+   :members:
+   :show-inheritance:
+
+
+The field_plugins module
+------------------------
+
+.. automodule:: empyre.io.field_plugins
+   :members:
+   :show-inheritance:

docs/vis.rst

@@ -3,6 +3,12 @@ The vis visualization submodule
 
 General empyre.vis docu here!
 
+All functions implemented in the subpackages can be accessed directly in the ``empyre.io`` namespace, with the exception
+of the ``color`` module, whose methods are accessible via ``empyre.vis.colors``.
+
+Note that the y-axis of all image plots is flipped in comparison to ``matplotlib.pyplot.imshow``, i.e. that the
+origin is `'lower'` in this case instead of `'upper'`.
+
 Please note that 3D plots only work in your Jupyter notebook after first installing and then enabling the corresponding
 mayavi extension:
 
@@ -11,6 +17,16 @@ mayavi extension:
       $ jupyter nbextension install --py mayavi --user
       $ jupyter nbextension enable mayavi --user --py
 
+If you'd like to utilize 3D plots in your Jupyter Notebook or in the Python Interactive Window
+
+.. code-block:: Python
+
+      >>> from mayavi import mlab
+      >>> mlab.init_notebook('x3d')
+
+The backend, chosen by the `init_notebook` function can be `ipy` (the default, produces static images in Juypter
+Notebook and does not work in VSCode), `x3d` (produces interactive plots in Jupyter Noteboo, but seems to not work with
+VSCode), or `png` (produces png-images, which work in both Jupyter Notebooks and VSCode).
 For more information and a quick introduction visit the `mayavi tips & tricks section <https://docs.enthought.com/mayavi/mayavi/tips.html>`_.