Merge pull request earthobservations#167 from panodata/sphinx-ipython

Add tutorial stub based on iPython Sphinx extension
panodata · Sep 21, 2020 · daee29d · daee29d
2 parents 42bf276 + dadc3c7
commit daee29d
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 12 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,6 +58,10 @@ def _get_project_meta():
     "sphinx_rtd_theme",
     "sphinxcontrib.rsvgconverter",
     "sphinx.ext.imgconverter",
+    #"matplotlib.sphinxext.only_directives",
+    "matplotlib.sphinxext.plot_directive",
+    "IPython.sphinxext.ipython_directive",
+    "IPython.sphinxext.ipython_console_highlighting",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/index.rst b/docs/index.rst
@@ -26,6 +26,7 @@ Usage
    :maxdepth: 1
 
    API overview <pages/api>
+   pages/tutorial
    pages/cli
    pages/library/index
    pages/behind_the_scenes

diff --git a/docs/pages/tutorial.rst b/docs/pages/tutorial.rst
@@ -0,0 +1,59 @@
+########
+Tutorial
+########
+
+
+=============
+Prerequisites
+=============
+Import modules necessary for general functioning.
+
+.. ipython::
+
+    In [1]: import warnings
+       ...: warnings.filterwarnings("ignore")
+       ...: import wetterdienst
+       ...: from wetterdienst import PeriodType, TimeResolution, Parameter
+       ...: import matplotlib as mpl
+       ...: import matplotlib.pyplot as plt
+       ...: from matplotlib import cm
+
+
+========
+Metadata
+========
+
+Which parameters are available?
+
+
+All available combinations
+==========================
+.. ipython::
+
+    In [2]: print(wetterdienst.discover_climate_observations())
+
+
+Daily historical data
+=====================
+.. ipython::
+
+    In [3]: print("Selection of daily historical data")
+       ...: print(
+       ...:     wetterdienst.discover_climate_observations(
+       ...:         time_resolution=TimeResolution.DAILY,
+       ...:         period_type=PeriodType.HISTORICAL
+       ...:     )
+       ...: )
+
+
+================
+Get station list
+================
+
+.. ipython::
+
+    In [1]: metadata_hdp = wetterdienst.metadata_for_climate_observations(
+       ...:     Parameter.PRECIPITATION_MORE, TimeResolution.DAILY, PeriodType.HISTORICAL)
+       ...: print("Number of stations with available data: ", metadata_hdp["HAS_FILE"].sum())
+       ...: print("Some of the stations:")
+       ...: metadata_hdp.head()
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -5,3 +5,4 @@ importlib_metadata==1.6.1
 tomlkit==0.7.0
 sphinx-autodoc-typehints==1.11.0
 sphinxcontrib-svg2pdfconverter==1.1.0
+matplotlib==3.3.2
diff --git a/wetterdienst/additionals/functions.py b/wetterdienst/additionals/functions.py
@@ -6,6 +6,7 @@
 import json
 
 import pandas as pd
+from numpy.distutils.misc_util import as_list
 
 from wetterdienst.constants.parameter_mapping import TIME_RESOLUTION_PARAMETER_MAPPING
 from wetterdienst.constants.time_resolution_mapping import (
@@ -339,6 +340,12 @@ def create_humanized_column_names_mapping(
     return column_name_mapping
 
 
+def parse_enumeration(template, values):
+    return list(
+        map(lambda x: parse_enumeration_from_template(x, template), as_list(values))
+    )
+
+
 def discover_climate_observations(
     time_resolution: Optional[TimeResolution] = None,
     parameter: Optional[Parameter] = None,
@@ -354,31 +361,26 @@ def discover_climate_observations(
 
     :return:                        Result of available combinations in JSON.
     """
+
     if not time_resolution:
         time_resolution = [*TimeResolution]
     if not parameter:
         parameter = [*Parameter]
     if not period_type:
         period_type = [*PeriodType]
 
-    time_resolution = pd.Series(time_resolution).apply(
-        parse_enumeration_from_template, args=(TimeResolution,)
-    )
-    parameter = pd.Series(parameter).apply(
-        parse_enumeration_from_template, args=(Parameter,)
-    )
-    period_type = pd.Series(period_type).apply(
-        parse_enumeration_from_template, args=(PeriodType,)
-    )
+    time_resolution = parse_enumeration(TimeResolution, time_resolution)
+    parameter = parse_enumeration(Parameter, parameter)
+    period_type = parse_enumeration(PeriodType, period_type)
 
     trp_mapping_filtered = {
         ts: {
-            par: [p for p in pt if p in period_type.values]
+            par: [p for p in pt if p in period_type]
             for par, pt in parameters_and_period_types.items()
-            if par in parameter.values
+            if par in parameter
         }
         for ts, parameters_and_period_types in TIME_RESOLUTION_PARAMETER_MAPPING.items()
-        if ts in time_resolution.values
+        if ts in time_resolution
     }
 
     time_resolution_parameter_mapping = {