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
GeoStat-Framework · Apr 16, 2023 · 4701260 · 4701260
1 parent 4c7b72a
commit 4701260
Show file tree

Hide file tree

Showing 35 changed files with 487 additions and 1,045 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,8 @@
 .spyproject/
 __pycache__/
 docs/build/
+docs/source/generated/
+docs/source/examples/
 info/
 #_build
 #_static

diff --git a/anaflow/__init__.py b/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::

diff --git a/anaflow/flow/__init__.py b/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
 """

diff --git a/docs/source/conf.py b/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')"),
+}
diff --git a/docs/source/contents.rst b/docs/source/contents.rst
@@ -7,5 +7,5 @@ Contents
    :maxdepth: 3
 
    index
-   tutorials
+   examples/index
    package
diff --git a/docs/source/flow.ext_grf_model.rst b/docs/source/flow.ext_grf_model.rst
diff --git a/docs/source/flow.heterogeneous.rst b/docs/source/flow.heterogeneous.rst
diff --git a/docs/source/flow.homogeneous.rst b/docs/source/flow.homogeneous.rst
diff --git a/docs/source/flow.rst b/docs/source/flow.rst
@@ -10,7 +10,4 @@ anaflow.flow
 .. toctree::
    :hidden:
 
-   flow.homogeneous.rst
-   flow.heterogeneous.rst
-   flow.ext_grf_model.rst
    flow.laplace.rst
diff --git a/docs/source/tutorial_01_call.rst b/docs/source/tutorial_01_call.rst
diff --git a/docs/source/tutorial_02_extended_theis.rst b/docs/source/tutorial_02_extended_theis.rst
diff --git a/docs/source/tutorial_03_extended_theis3d.rst b/docs/source/tutorial_03_extended_theis3d.rst