Tutorials initial structure (#52)

* move user guide to tutorials * finabele of FAIR priciples * reorganise old tutorials * delete roadmap * exclude gitinclude * organise bib files * Fair principles * move install and admin to tutorials * initial structure of tutorials * include notebooks * include raven * reorganisation of Guidelines * review of fair principles * add initial server guide * fair guiding principles * move make a bird to tutorial section * change header * tutorial server * reorganisation of introduction * resolve merge conflict * include initial basic tutorial * content for birds tutorial section * lower header for conda environment * linked in the cookie-cutter dev guide * tutorial pywps including * pywps tutorial file
bird-house · Oct 1, 2020 · 1bf3ce4 · 1bf3ce4
1 parent 0be4a75
commit 1bf3ce4
Show file tree

Hide file tree

Showing 12 changed files with 157 additions and 163 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -35,9 +35,29 @@
     'sphinx.ext.viewcode',
     'sphinxcontrib.bibtex',
     'sphinx.ext.graphviz',
-    'docaggregation'
+    'docaggregation',
+    "nbsphinx",
+    'sphinx.ext.mathjax',
 ]
 
+nbsphinx_allow_errors = True
+
+# extensions = [
+#     "sphinx.ext.autodoc",
+#     "sphinx.ext.viewcode",
+#     "sphinx.ext.mathjax",
+#     "sphinx.ext.napoleon",
+#     "sphinx.ext.todo",
+#     "pywps.ext_autodoc",
+#     "sphinx.ext.autosectionlabel",
+#     "sphinx.ext.imgconverter",
+#     "nbsphinx",
+#     "IPython.sphinxext.ipython_console_highlighting",
+#     # "sphinx.ext.intersphinx",
+#     # "docaggregation",
+# ]
+
+
 # autoapi_type = 'python'
 # autoapi_dirs = ['../../.']
 # autoapi_file_pattern = '*.py'
@@ -88,7 +108,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

diff --git a/docs/source/guide_WPS.rst b/docs/source/guide_WPS.rst
@@ -9,6 +9,24 @@ WPS design
     :depth: 1
 
 
+
+Setting up a new WPS
+====================
+
+If you are familiar with all the upper chapters you are ready to create your own WPS.
+The WPS in birdhouse are named after birds, so this section is giving you a guidline of how to make your own bird. Birds are sorted thematically, so before setting up a new one, make sure it is not already covered and just missing some processes and be clear in the new thematic you would like to provide.
+
+There is a Cookiecutter_ template to create a new bird (PyWPS application).
+It is the recommended and fastest way to create your own bird:
+
+
+.. gittoctree:: https://github.com/bird-house/cookiecutter-birdhouse.git
+
+  docs/source/dev_guide.rst
+
+.. gitinclude:: https://github.com/bird-house/cookiecutter-birdhouse/blob/master/%7B%7Bcookiecutter.project_repo_name%7D%7D/docs/source/dev_guide.rst
+
+
 .. _writing_WPS_process:
 
 Writing a WPS process

diff --git a/docs/source/guide_dev.rst b/docs/source/guide_dev.rst
@@ -1,7 +1,7 @@
 .. _guide_guide:
 
-Coding guide
-============
+Software development
+====================
 
 
 .. contents::

diff --git a/docs/source/projects.rst b/docs/source/projects.rst
@@ -6,7 +6,7 @@ Project examples
 
 .. contents::
     :local:
-    :depth: 3
+    :depth: 1
 
 The birdhouse :ref:`framework is modular organized <framework_structure>` to enable a flexible architecture design depending on the projects needs. Due to the OCG Standard, software components non-birdhouse components can be combined for interoperability. Here are some examples of real projects to show the flexibility and potential of the birdhouse framework.
 

diff --git a/docs/source/tutorial_basic.rst b/docs/source/tutorial_basic.rst
@@ -0,0 +1,13 @@
+.. _tutorials_basic:
+
+
+Climate Data with Phyton
+........................
+
+Introduction to basic processing of climate data
+
+.. gittoctree:: https://github.com/nilshempelmann/climdatatutorial.git
+
+  /docs/source/notebooks/index.rst
+
+.. gitinclude:: https://github.com/nilshempelmann/climdatatutorial/blob/master/docs/source/notebooks/index.rst
diff --git a/docs/source/tutorial_birds.rst b/docs/source/tutorial_birds.rst
@@ -0,0 +1,46 @@
+WPS services of birdhouse
+=========================
+
+The following section are tutorials of the different components of birdhouse.
+
+.. contents::
+    :local:
+    :depth: 1
+
+
+Hello World WPS (emu):
+......................
+
+* :ref:`Emu Example with Docker <emu:tutorial>`
+
+WPS client (birdy):
+...................
+
+* :ref:`Example with Birdy WPS command line tool <birdy:tutorial>`
+
+
+Climate Indices (finch):
+........................
+
+WPS finch is providing services to calculate climate indices widely used in climate change adaptation planing processes.
+
+.. gittoctree:: https://github.com/bird-house/finch.git
+
+  docs/source/notebooks/index.rst
+
+
+.. gitinclude:: https://github.com/bird-house/finch/blob/master/docs/source/notebooks/index.rst
+
+
+
+Hydrological models (raven):
+............................
+
+WPS raven is providing hydrological models for e.g. hydro-power controlling and sustainable planing
+
+.. gittoctree:: https://github.com/Ouranosinc/raven.git
+
+   docs/source/notebooks/index.rst
+
+
+.. gitinclude:: https://github.com/Ouranosinc/raven/blob/master/docs/source/notebooks/index.rst
diff --git a/docs/source/tutorial_install.rst b/docs/source/tutorial_install.rst
@@ -1,4 +1,4 @@
-.. _guide_install:
+.. _tutorial_install:
 
 birdhouse installation
 =======================

diff --git a/docs/source/tutorial_pywps.rst b/docs/source/tutorial_pywps.rst
@@ -0,0 +1,12 @@
+.. _tutorial_pywps:
+
+
+Getting started with PYWPS
+..........................
+
+.. gittoctree:: https://github.com/bird-house/birdhouse-workshop.git
+
+  /docs/source/index.rst
+
+
+.. gitinclude:: https://github.com/bird-house/birdhouse-workshop/blob/master/docs/source/index.rst
diff --git a/docs/source/tutorial_server.rst b/docs/source/tutorial_server.rst
@@ -0,0 +1,10 @@
+.. _tutorial_server
+
+Server administration
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial_install
+   tutorial_admin
diff --git a/docs/source/tutorial_wps.rst b/docs/source/tutorial_wps.rst
@@ -1,7 +1,7 @@
 .. _wps_tutorial:
 
-Wordcounter Example
-===================
+
+WPS general usage
 
 .. todo:: The WPS tutorial needs to be updated.
 
@@ -61,7 +61,7 @@ For more details see the following `WPS Tutorial`_.
 .. _chaining_WPS:
 
 Chaining WPS processes
-----------------------
+======================
 
 If you know the input/output parameters of processes you can chain processes. For example we will chain a `Text Generator` process to
 our `Word Counter` process.
@@ -172,6 +172,25 @@ Run `wordcount` with a text document (`Execute`)::
   Output:
   output=http://localhost:8090/wpsoutputs/emu/output-37445d08-cf0f-11e4-ab7e-68f72837e1b4.txt
 
+
+Environment with conda
+......................
+
+.. todo:: How to create a conda package
+
+
+.. _python_guide:
+
+Python syntax:
+..............
+
+.. code:: ipython3
+
+    """Python WPS execute"""
+
+    from owslib.wps import WebProcessingService, monitorExecution
+    from os import system
+
 ..  _WPS Tutorial: http://wiki.ieee-earth.org/Documents/GEOSS_Tutorials/GEOSS_Provider_Tutorials/Web_Processing_Service_Tutorial_for_GEOSS_Providers/Section_2:_Introduction_to_WPS
 
 .. rubric:: Footnotes

diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -3,163 +3,16 @@
 **********
 Tutorials
 **********
-.. contents::
-    :local:
-    :depth: 3
 
-To guide you through the learning curve of installation modules of birdhouse and set up an running birdhouse ecosystem, administer the server-side birdhouse components or even improve and develop your own specific functions, here are some general tutorials. This is a collection of tutorials and examples covering to show usage of WPS services but is also covering general data management with an focus on sustainable development.
+.. warning::
+    Work in progress!!
 
-If you are a newcommer, you might have to go through a basic python tutorial first:
-.. todo:: Python tutorial
-
-Climate data management
------------------------
-**general Tutorial** about climate and related data handling.
-
-* esfg-python client
-
-
-WPS general usage
------------------
-General concepts and tutorials for pyWPS:
-
-* `PyWPS 4.0.0 Slides <http://www.slideshare.net/jachym/pywps400>`_
-* `PyWPS Documentation <https://pywps.readthedocs.io/en/master/process.html>`_
-
-You can connect to a WPS service in the following ways:
-
-* using a command-line tool in your terminal.
-* using a web based application from your browser.
-* using a Python library from a jupyter notebook or your Python scripts.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
+   tutorial_basic
+   tutorial_pywps
    tutorial_wps
-   tutorial_install
-   tutorial_admin
-
-
-
-.. gittoctree:: https://github.com/bird-house/finch.git
-
-  docs/source/notebooks/index.rst
-
-
-.. gitinclude:: https://github.com/bird-house/finch/blob/master/docs/source/notebooks/index.rst
-
-
-
-.. todo:: birdy example
-.. todo:: Screen-shot of Phoenix
-
-
-Environment with conda
-......................
-
-.. todo:: How to create a conda package
-
-
-Make your own Bird
-..................
-
-If you are familiar with all the upper chapters you are ready to create your own WPS. The WPS in birdhouse are named after birds, so this section is giving you a guidline of how to make your own bird. Birds are sorted thematically, so before setting up a new one, make sure it is not already covered and just missing some processes and be clear in the new thematic you would like to provide.
-
-We have now a Cookiecutter_ template to create a new bird (PyWPS application).
-It is the recommended and fastest way to create your own bird:
-
-https://github.com/bird-house/cookiecutter-birdhouse
-
-.. note:: The cookiecutter is brand-new. Please give feedback and help to improve it.
-
-
-
-WPS services of birdhouse
--------------------------
-
-* Climate Indices (finch):
-
-
-.. _python_guide:
-
-Python syntax:
-==============
-
-.. code:: ipython3
-
-    """Python WPS execute"""
-
-    from owslib.wps import WebProcessingService, monitorExecution
-    from os import system
-
-
-.. code:: ipython3
-
-    wps = WebProcessingService(url="http://localhost:8093/wps", verbose=False)
-    print("Service '{}' is running".format(wps.identification.title))
-
-
-.. parsed-literal::
-
-    Service 'Flyingpigeon' is running
-
-
-.. code:: ipython3
-
-    for process in wps.processes:
-        print( '{} : \t {}'.format(process.identifier, process.abstract))
-
-
-.. parsed-literal::
-
-    subset : 	 Return the data for which grid cells intersect the selected polygon for each input dataset as well asthe time range selected.
-    subset_bbox : 	 Return the data for which grid cells intersect the bounding box for each input dataset as well asthe time range selected.
-    subset_continents : 	 Return the data whose grid cells intersect the selected continents for each input dataset.
-    subset_countries : 	 Return the data whose grid cells intersect the selected countries for each input dataset.
-    pointinspection : 	 Extract the timeseries at the given coordinates.
-    subset_WFS : 	 Return the data for which grid cells intersect the selected polygon for each input dataset.
-    plot_timeseries : 	 Outputs some timeseries of the file field means. Spaghetti and uncertainty plot
-
-
-.. code:: ipython3
-
-    # define some data urls
-
-    url1 = 'https://www.esrl.noaa.gov/psd/thredds/fileServer/Datasets/ncep.reanalysis.dailyavgs/surface/slp.2000.nc'
-    url2 = 'https://www.esrl.noaa.gov/psd/thredds/fileServer/Datasets/ncep.reanalysis.dailyavgs/surface/slp.2001.nc'
-    url3 = 'https://www.esrl.noaa.gov/psd/thredds/fileServer/Datasets/ncep.reanalysis.dailyavgs/surface/slp.2002.nc'
-    url4 = 'https://www.esrl.noaa.gov/psd/thredds/fileServer/Datasets/ncep.reanalysis.dailyavgs/surface/slp.2003.nc'
-
-.. code:: ipython3
-
-    execute = wps.execute(
-        identifier="plot_timeseries", #indices_clipping",
-        inputs=[
-           ("resource",url1),
-           ("resource",url2),
-           ("resource",url3),
-           ("resource",url4),
-           # ("variable" , "slp"),
-           ])
-
-    monitorExecution(execute, sleepSecs=5)
-    print(execute.getStatus())
-
-    for o in execute.processOutputs:
-        print(o.reference)
-
-
-.. parsed-literal::
-
-     owslib.wps.WPSException : {'code': 'NoApplicableCode', 'locator': 'None', 'text': 'Process failed, please check server error log'}
-    ProcessFailed
-
-
-.. code:: ipython3
-
-    from eggshell.nc.nc_utils import get_coordinates
-
-
-
-* :ref:`Emu Example with Docker <emu:tutorial>`
-* :ref:`Example with Birdy WPS command line tool <birdy:tutorial>`
+   tutorial_server
+   tutorial_birds