doc: move to sphinx gallery (#8)

* doc: move to sphinx gallery

* doc: auto generate toc-tree for flow submodule

* doc: gitignore generated examples

* doc: remove generated examples

Author: MuellerSeb

.gitignore

@@ -4,6 +4,8 @@
 .spyproject/
 __pycache__/
 docs/build/
+docs/source/generated/
+docs/source/examples/
 info/
 #_build
 #_static

anaflow/__init__.py

@@ -19,7 +19,7 @@
 Homogeneous
 ^^^^^^^^^^^
 
-.. currentmodule:: anaflow.flow.homogeneous
+.. currentmodule:: anaflow.flow
 
 Solutions for homogeneous aquifers
 
@@ -31,8 +31,6 @@
 Heterogeneous
 ^^^^^^^^^^^^^
 
-.. currentmodule:: anaflow.flow.heterogeneous
-
 Solutions for heterogeneous aquifers
 
 .. autosummary::
@@ -50,8 +48,6 @@
 Extended GRF
 ^^^^^^^^^^^^
 
-.. currentmodule:: anaflow.flow.ext_grf_model
-
 The extended general radial flow model.
 
 .. autosummary::

anaflow/flow/__init__.py

@@ -8,9 +8,6 @@
 .. currentmodule:: anaflow.flow
 
 .. autosummary::
-    homogeneous
-    heterogeneous
-    ext_grf_model
     laplace
 
 Solutions
@@ -19,42 +16,42 @@
 Homogeneous
 ~~~~~~~~~~~
 
-.. currentmodule:: anaflow.flow.homogeneous
-
 Solutions for homogeneous aquifers
 
 .. autosummary::
+   :toctree: generated
+
    thiem
    theis
    grf
 
 Heterogeneous
 ~~~~~~~~~~~~~
 
-.. currentmodule:: anaflow.flow.heterogeneous
-
 Solutions for heterogeneous aquifers
 
 .. autosummary::
+   :toctree: generated
+
    ext_thiem_2d
    ext_thiem_3d
    ext_thiem_tpl
    ext_thiem_tpl_3d
    ext_theis_2d
    ext_theis_3d
    ext_theis_tpl
-   ext_thiem_tpl_3d
+   ext_theis_tpl_3d
    neuman2004
    neuman2004_steady
 
 Extended GRF
 ~~~~~~~~~~~~
 
-.. currentmodule:: anaflow.flow.ext_grf_model
-
 The extended general radial flow model.
 
 .. autosummary::
+   :toctree: generated
+
    ext_grf
    ext_grf_steady
 """

docs/source/conf.py

@@ -54,6 +54,7 @@ def setup(app):
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",  # parameters look better than with numpydoc only
     "numpydoc",
+    "sphinx_gallery.gen_gallery",
 ]
 
 # autosummaries from source-files
@@ -242,3 +243,30 @@ def setup(app):
     "NumPy": ("http://docs.scipy.org/doc/numpy/", None),
     "SciPy": ("http://docs.scipy.org/doc/scipy/reference", None),
 }
+
+# -- Sphinx Gallery Options
+from sphinx_gallery.sorting import FileNameSortKey
+
+sphinx_gallery_conf = {
+    # only show "print" output as output
+    "capture_repr": (),
+    # path to your examples scripts
+    "examples_dirs": ["../../examples"],
+    # path where to save gallery generated examples
+    "gallery_dirs": ["examples"],
+    # Pattern to search for example files
+    "filename_pattern": "/.*.py",
+    # "ignore_pattern": "",
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example by file name instead of number of lines (default)
+    "within_subsection_order": FileNameSortKey,
+    # directory where function granular galleries are stored
+    "backreferences_dir": None,
+    # Modules for which function level galleries are created.  In
+    "doc_module": "AnaFlow",
+    # "image_scrapers": ('pyvista', 'matplotlib'),
+    # "first_notebook_cell": ("%matplotlib inline\n"
+    #                         "from pyvista import set_plot_theme\n"
+    #                         "set_plot_theme('document')"),
+}

docs/source/contents.rst

@@ -7,5 +7,5 @@ Contents
    :maxdepth: 3
 
    index
-   tutorials
+   examples/index
    package

docs/source/flow.ext_grf_model.rst

@@ -10,7 +10,4 @@ anaflow.flow
 .. toctree::
    :hidden:
 
-   flow.homogeneous.rst
-   flow.heterogeneous.rst
-   flow.ext_grf_model.rst
    flow.laplace.rst