doc: move to sphinx gallery

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/examples/01_call_theis.ipynb

@@ -0,0 +1,54 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "%matplotlib inline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# The Theis solution\n\nIn the following the well known Theis function is called an plotted for three\ndifferent time-steps.\n\nReference: `Theis 1935 <https://doi.org/10.1029/TR016i002p00519>`__\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import numpy as np\nfrom matplotlib import pyplot as plt\nfrom anaflow import theis\n\n\ntime = [10, 100, 1000]\nrad = np.geomspace(0.1, 10)\n\nhead = theis(time=time, rad=rad, storage=1e-4, transmissivity=1e-4, rate=-1e-4)\n\nfor i, step in enumerate(time):\n    plt.plot(rad, head[i], label=\"Theis(t={})\".format(step))\n\nplt.legend()\nplt.tight_layout()\nplt.show()"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.6.9"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

docs/source/examples/01_call_theis.py

@@ -0,0 +1,25 @@
+r"""
+The Theis solution
+==================
+
+In the following the well known Theis function is called an plotted for three
+different time-steps.
+
+Reference: `Theis 1935 <https://doi.org/10.1029/TR016i002p00519>`__
+"""
+import numpy as np
+from matplotlib import pyplot as plt
+from anaflow import theis
+
+
+time = [10, 100, 1000]
+rad = np.geomspace(0.1, 10)
+
+head = theis(time=time, rad=rad, storage=1e-4, transmissivity=1e-4, rate=-1e-4)
+
+for i, step in enumerate(time):
+    plt.plot(rad, head[i], label="Theis(t={})".format(step))
+
+plt.legend()
+plt.tight_layout()
+plt.show()

docs/source/examples/01_call_theis.py.md5

@@ -0,0 +1 @@
+b1aeb7d2930d746b1355d09b73b76480

docs/source/examples/01_call_theis.rst

@@ -0,0 +1,91 @@
+
+.. DO NOT EDIT.
+.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
+.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
+.. "examples/01_call_theis.py"
+.. LINE NUMBERS ARE GIVEN BELOW.
+
+.. only:: html
+
+    .. note::
+        :class: sphx-glr-download-link-note
+
+        Click :ref:`here <sphx_glr_download_examples_01_call_theis.py>`
+        to download the full example code
+
+.. rst-class:: sphx-glr-example-title
+
+.. _sphx_glr_examples_01_call_theis.py:
+
+
+The Theis solution
+==================
+
+In the following the well known Theis function is called an plotted for three
+different time-steps.
+
+Reference: `Theis 1935 <https://doi.org/10.1029/TR016i002p00519>`__
+
+.. GENERATED FROM PYTHON SOURCE LINES 10-26
+
+
+
+.. image:: /examples/images/sphx_glr_01_call_theis_001.png
+    :alt: 01 call theis
+    :class: sphx-glr-single-img
+
+
+
+
+
+.. code-block:: default
+
+    import numpy as np
+    from matplotlib import pyplot as plt
+    from anaflow import theis
+
+
+    time = [10, 100, 1000]
+    rad = np.geomspace(0.1, 10)
+
+    head = theis(time=time, rad=rad, storage=1e-4, transmissivity=1e-4, rate=-1e-4)
+
+    for i, step in enumerate(time):
+        plt.plot(rad, head[i], label="Theis(t={})".format(step))
+
+    plt.legend()
+    plt.tight_layout()
+    plt.show()
+
+
+.. rst-class:: sphx-glr-timing
+
+   **Total running time of the script:** ( 0 minutes  0.325 seconds)
+
+
+.. _sphx_glr_download_examples_01_call_theis.py:
+
+
+.. only :: html
+
+ .. container:: sphx-glr-footer
+    :class: sphx-glr-footer-example
+
+
+
+  .. container:: sphx-glr-download sphx-glr-download-python
+
+     :download:`Download Python source code: 01_call_theis.py <01_call_theis.py>`
+
+
+
+  .. container:: sphx-glr-download sphx-glr-download-jupyter
+
+     :download:`Download Jupyter notebook: 01_call_theis.ipynb <01_call_theis.ipynb>`
+
+
+.. only:: html
+
+ .. rst-class:: sphx-glr-signature
+
+    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_

docs/source/examples/02_call_ext_theis2d.ipynb

@@ -0,0 +1,126 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "%matplotlib inline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# The extended Theis solution in 2D\n\nWe provide an extended theis solution, that incorporates the effectes of a\nheterogeneous transmissivity field on a pumping test.\n\nIn the following this extended solution is compared to the standard theis\nsolution for well flow. You can nicely see, that the extended solution represents\na transition between the theis solutions for the geometric- and harmonic-mean\ntransmissivity.\n\nReference: `Zech et. al. 2016 <http://dx.doi.org/10.1002/2015WR018509>`__\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import numpy as np\nfrom matplotlib import pyplot as plt\nfrom anaflow import theis, ext_theis_2d"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We use three time steps: 10s, 10min, 10h\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "time_labels = [\"10 s\", \"10 min\", \"10 h\"]\ntime = [10, 600, 36000]  # 10s, 10min, 10h"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Radius from the pumping well should be in [0, 4].\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "rad = np.geomspace(0.05, 4)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Parameters of heterogeneity, storage and pumping rate.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "var = 0.5  # variance of the log-transmissivity\nlen_scale = 10.0  # correlation length of the log-transmissivity\nTG = 1e-4  # the geometric mean of the transmissivity\nTH = TG * np.exp(-var / 2.0)  # the harmonic mean of the transmissivity\n\nS = 1e-4  # storativity\nrate = -1e-4  # pumping rate"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now let's compare the extended Theis solution to the classical solutions\nfor the near and far field values of transmissivity.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "head_TG = theis(time, rad, S, TG, rate)\nhead_TH = theis(time, rad, S, TH, rate)\nhead_ef = ext_theis_2d(time, rad, S, TG, var, len_scale, rate)\ntime_ticks = []\nfor i, step in enumerate(time):\n    label_TG = \"Theis($T_G$)\" if i == 0 else None\n    label_TH = \"Theis($T_H$)\" if i == 0 else None\n    label_ef = \"extended Theis\" if i == 0 else None\n    plt.plot(\n        rad, head_TG[i], label=label_TG, color=\"C\" + str(i), linestyle=\"--\"\n    )\n    plt.plot(\n        rad, head_TH[i], label=label_TH, color=\"C\" + str(i), linestyle=\":\"\n    )\n    plt.plot(rad, head_ef[i], label=label_ef, color=\"C\" + str(i))\n    time_ticks.append(head_ef[i][-1])\n\nplt.xlabel(\"r in [m]\")\nplt.ylabel(\"h in [m]\")\nplt.legend()\nylim = plt.gca().get_ylim()\nplt.gca().set_xlim([0, rad[-1]])\nax2 = plt.gca().twinx()\nax2.set_yticks(time_ticks)\nax2.set_yticklabels(time_labels)\nax2.set_ylim(ylim)\nplt.tight_layout()\nplt.show()"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.6.9"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}