Adds the examples as literal includes to the docs (#244)

autogenerate literal include docs for all examples. The code is self maintaining: if examples are removed or added the docs are also updated. * autogenerate documentation on the basis of the examples including notebooks * renaming of examples * seperate notebooks and other examples in the toctree
quaquel · Apr 7, 2023 · 081b41f · 081b41f
1 parent 17fc315
commit 081b41f
Show file tree

Hide file tree

Showing 91 changed files with 3,492 additions and 160 deletions.
diff --git a/docs/source/basic_tutorial.rst b/docs/source/basic_tutorial.rst
@@ -67,7 +67,7 @@ sampling are also readily available. Read the documentation for
 
 .. rubric:: The complete code:
 
-.. literalinclude:: ../../ema_workbench/examples/python_example.py
+.. literalinclude:: ../../ema_workbench/examples/example_python.py
    :linenos:
 
 .. _A-simple-model-in-Vensim:
@@ -121,7 +121,7 @@ code, messages on progress or on errors will be shown.
 
 .. rubric:: The complete code
 
-.. literalinclude:: ../../ema_workbench/examples/vensim_example.py
+.. literalinclude:: ../../ema_workbench/examples/example_vensim.py
    :linenos:
 
 .. _A-simple-model-in-Excel:
@@ -140,7 +140,7 @@ the decimal separator and thousands separator are set correctly in Excel. This
 can be checked via file > options > advanced. These separators should follow
 the `anglo saxon convention <http://en.wikipedia.org/wiki/Decimal_mark>`_.
 
-.. literalinclude:: ../../ema_workbench/examples/excel_example.py
+.. literalinclude:: ../../ema_workbench/examples/example_excel.py
    :linenos:
 
 The example is relatively straight forward. We instantiate an excel model, we
@@ -242,7 +242,7 @@ normal contact rate region 2                             10             200
 
 Together, this results in the following code:
 
-.. literalinclude:: ../../ema_workbench/examples/flu_vensim_no_policy_example.py
+.. literalinclude:: ../../ema_workbench/examples/example_vensim_no_policy_flu.py
    :linenos:
 
 We have now instantiated the model, specified the uncertain factors and outcomes
@@ -273,7 +273,7 @@ for a series of experiments and save these results. One can then use these
 saved results in various analysis scripts. ::
 
    from ema_workbench import save_results
-   save_results(results, r'./1000 runs.tar.gz')
+   save_results(results, './1000 runs.tar.gz')
 
 The above code snippet shows how we can use :func:`~util.save_results` for
 saving the results of our experiments. :func:`~util.save_results` stores the as
@@ -321,7 +321,7 @@ argument ::
 We can now proceed in the same way as before, and perform a series of
 experiments. Together, this results in the following code:
 
-.. literalinclude:: ../../ema_workbench/examples/flu_vensim_example.py
+.. literalinclude:: ../../ema_workbench/examples/example_vensim_flu.py
    :linenos:
 
 comparison of results
@@ -333,7 +333,7 @@ But using :func:`pairs_scatter`. It shows for the three different policies
 their behavior on the total number of deaths, the height of the highest peak
 of the pandemic, and the point in time at which this peak was reached.
 
-.. literalinclude:: ../../ema_workbench/examples/flu_pairsplot.py
+.. literalinclude:: ../../ema_workbench/examples/plotting_pairsplot_flu.py
    :linenos:
 
 .. rubric:: no policy

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -13,11 +13,13 @@
 serve to show the default.
 """
 
+import glob
 import sys
 import os
 import os.path as osp
 import re
 import shutil
+import string
 
 HERE = osp.abspath(osp.dirname(__file__))
 
@@ -260,7 +262,76 @@ def establish_version():
 man_pages = [("index", "emaworkbench", "EMA workbench Documentation", ["J.H. Kwakkel"], 1)]
 
 
+def setup_examples_pages():
+    # create rst files for all examples
+    # check what examples exist
+    examples_folder = osp.join(HERE, "..", "..", "ema_workbench", "examples")
+    examples = glob.glob(examples_folder + "/*.py")
+    ignore_list = {"__init__", "test_examples", "model_debugger"}
+
+    # get all existing rst files
+    rst_files = glob.glob(os.path.join(HERE, "examples", "*.rst"))
+    rst_files = {os.path.basename(os.path.normpath(entry)) for entry in rst_files}
+
+    # check which rst files exist
+    # TODO:: consider stripping out top level docstring and add this as normal text to example
+    # TODO then only include remaining lines.
+    with open(os.path.join(HERE, "example_template.txt")) as fh:
+        template = string.Template(fh.read())
+
+    # TODO:: at the moment no idea what happens if example is updated. Does this trigger a rebuild of the html page?
+    examples_rst = []
+    for example in examples:
+        base_name = os.path.basename(os.path.normpath(example))
+        base, ext = os.path.splitext(base_name)
+        if base in ignore_list:
+            continue
+
+        short_py_filename = f"{base}.py"
+        short_rst_filename = f"{base}.rst"
+        headerline = "=" * len(short_py_filename)
+        examples_rst.append(f"./examples/{short_rst_filename}")
+
+        if short_rst_filename not in rst_files:
+            with open(os.path.join(HERE, "examples", short_rst_filename), "w") as fh:
+                content = template.substitute(
+                    dict(short_filename=short_py_filename, headerline=headerline)
+                )
+                fh.write(content)
+        else:
+            rst_files.remove(short_rst_filename)
+
+    # these rst files are outdated because the example has been removed
+    for entry in rst_files:
+        fn = os.path.join(HERE, "examples", entry)
+        os.remove(fn)
+
+    # copy and overwrite all notebooks
+    # TODO:: make this smarter by only copying if timestamp is newer of file does not exist
+    notebooks = glob.glob(examples_folder + "/*.ipynb")
+    notebook_files = []
+    for entry in notebooks:
+        base_name = os.path.basename(os.path.normpath(entry))
+        notebook_files.append(f"./examples/{base_name}")
+        shutil.copy(entry, os.path.join(HERE, "examples", base_name))
+        print(entry)
+
+    # creeate examples.rst
+    with open(os.path.join(HERE, "examples_template.txt")) as fh:
+        template = string.Template(fh.read())
+
+    with open(os.path.join(HERE, "examples.rst"), "w") as fh:
+        content = template.substitute(
+            dict(
+                notebooks="\n    ".join(sorted(notebook_files)),
+                python_files="\n    ".join(sorted(examples_rst)),
+            )
+        )
+        fh.write(content)
+
+
 def setup(app):
     # copy changelog into source folder for documentation
     dest = osp.join(HERE, "./getting_started/changelog.md")
     shutil.copy(osp.join(HERE, "..", "..", "CHANGELOG.md"), dest)
+    setup_examples_pages()
diff --git a/docs/source/example_template.txt b/docs/source/example_template.txt
@@ -0,0 +1,10 @@
+.. meta::
+   :description: $short_filename
+
+$headerline
+$short_filename
+$headerline
+
+
+.. literalinclude:: ../../../ema_workbench/examples/$short_filename
+   :linenos:
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,62 @@
+.. meta::
+   :description: Overview of all available examples
+
+
+********
+Examples
+********
+
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Notebooks
+
+    ./examples/outputspace_exploration_lakeproblem.ipynb
+    ./examples/scenario_discovery.ipynb
+    ./examples/vadere_demo.ipynb
+
+
+.. toctree::
+    :maxdepth: 1
+    :caption: python examples
+
+    ./examples/example_eijgenraam.rst
+    ./examples/example_excel.rst
+    ./examples/example_flu.rst
+    ./examples/example_lake_model.rst
+    ./examples/example_netlogo.rst
+    ./examples/example_pysd_teacup.rst
+    ./examples/example_python.rst
+    ./examples/example_simio.rst
+    ./examples/example_vensim.rst
+    ./examples/example_vensim_advanced_flu.rst
+    ./examples/example_vensim_flu.rst
+    ./examples/example_vensim_lookup.rst
+    ./examples/example_vensim_no_policy_flu.rst
+    ./examples/example_vensim_scarcity.rst
+    ./examples/feature_scoring_flu.rst
+    ./examples/feature_scoring_flu_confidence.rst
+    ./examples/feature_scoring_flu_overtime.rst
+    ./examples/optimization_lake_model_dps.rst
+    ./examples/optimization_lake_model_intertemporal.rst
+    ./examples/outputspace_exploration_lake_model.rst
+    ./examples/plotting_envelopes_flu.rst
+    ./examples/plotting_envelopes_with_lines_flu.rst
+    ./examples/plotting_kdeovertime_flu.rst
+    ./examples/plotting_lines_flu.rst
+    ./examples/plotting_multiple_densities_flu.rst
+    ./examples/plotting_pairsplot_flu.rst
+    ./examples/robust_optimization_lake_model_dps.rst
+    ./examples/sample_jointly_lake_model.rst
+    ./examples/sample_sobol_lake_model.rst
+    ./examples/sd_boostedtrees_flu.rst
+    ./examples/sd_cart_flu.rst
+    ./examples/sd_cart_wcm.rst
+    ./examples/sd_dimensional_stacking_flu.rst
+    ./examples/sd_logit_flu_example.rst
+    ./examples/sd_prim_PCA_flu.rst
+    ./examples/sd_prim_byrant_and_lempert.rst
+    ./examples/sd_prim_constrained.rst
+    ./examples/sd_prim_flu.rst
+    ./examples/sd_prim_wcm.rst
+    ./examples/timeseries_clustering_flu.rst
diff --git a/docs/source/examples/example_eijgenraam.rst b/docs/source/examples/example_eijgenraam.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_eijgenraam.py
+
+=====================
+example_eijgenraam.py
+=====================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_eijgenraam.py
+   :linenos:
diff --git a/docs/source/examples/example_excel.rst b/docs/source/examples/example_excel.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_excel.py
+
+================
+example_excel.py
+================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_excel.py
+   :linenos:
diff --git a/docs/source/examples/example_flu.rst b/docs/source/examples/example_flu.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_flu.py
+
+==============
+example_flu.py
+==============
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_flu.py
+   :linenos:
diff --git a/docs/source/examples/example_lake_model.rst b/docs/source/examples/example_lake_model.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_lake_model.py
+
+=====================
+example_lake_model.py
+=====================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_lake_model.py
+   :linenos:
diff --git a/docs/source/examples/example_netlogo.rst b/docs/source/examples/example_netlogo.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_netlogo.py
+
+==================
+example_netlogo.py
+==================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_netlogo.py
+   :linenos:
diff --git a/docs/source/examples/example_pysd_teacup.rst b/docs/source/examples/example_pysd_teacup.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_pysd_teacup.py
+
+======================
+example_pysd_teacup.py
+======================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_pysd_teacup.py
+   :linenos:
diff --git a/docs/source/examples/example_python.rst b/docs/source/examples/example_python.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_python.py
+
+=================
+example_python.py
+=================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_python.py
+   :linenos:
diff --git a/docs/source/examples/example_simio.rst b/docs/source/examples/example_simio.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_simio.py
+
+================
+example_simio.py
+================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_simio.py
+   :linenos:
diff --git a/docs/source/examples/example_vensim.rst b/docs/source/examples/example_vensim.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_vensim.py
+
+=================
+example_vensim.py
+=================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_vensim.py
+   :linenos:
diff --git a/docs/source/examples/example_vensim_advanced_flu.rst b/docs/source/examples/example_vensim_advanced_flu.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_vensim_advanced_flu.py
+
+==============================
+example_vensim_advanced_flu.py
+==============================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_vensim_advanced_flu.py
+   :linenos:
diff --git a/docs/source/examples/example_vensim_flu.rst b/docs/source/examples/example_vensim_flu.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_vensim_flu.py
+
+=====================
+example_vensim_flu.py
+=====================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_vensim_flu.py
+   :linenos:
diff --git a/docs/source/examples/example_vensim_lookup.rst b/docs/source/examples/example_vensim_lookup.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_vensim_lookup.py
+
+========================
+example_vensim_lookup.py
+========================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_vensim_lookup.py
+   :linenos:
diff --git a/docs/source/examples/example_vensim_no_policy_flu.rst b/docs/source/examples/example_vensim_no_policy_flu.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_vensim_no_policy_flu.py
+
+===============================
+example_vensim_no_policy_flu.py
+===============================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_vensim_no_policy_flu.py
+   :linenos:
diff --git a/docs/source/examples/example_vensim_scarcity.rst b/docs/source/examples/example_vensim_scarcity.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: example_vensim_scarcity.py
+
+==========================
+example_vensim_scarcity.py
+==========================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/example_vensim_scarcity.py
+   :linenos:
diff --git a/docs/source/examples/feature_scoring_flu.rst b/docs/source/examples/feature_scoring_flu.rst
@@ -0,0 +1,10 @@
+.. meta::
+   :description: feature_scoring_flu.py
+
+======================
+feature_scoring_flu.py
+======================
+
+
+.. literalinclude:: ../../../ema_workbench/examples/feature_scoring_flu.py
+   :linenos: