ENH: update doc structure for REL 1.3.0

kmuehlbauer · kmuehlbauer · commit 4465b584200a · 2019-03-29T14:07:02.000+01:00
diff --git a/requirements.txt b/requirements.txt
@@ -7,3 +7,4 @@ deprecation
 nbsphinx
 xmltodict
 semver
+xarray
diff --git a/source/conf.py b/source/conf.py
@@ -138,7 +138,7 @@ def __getattr__(cls, name):
                 'mpl_toolkits.axisartist.angle_helper',
                 'h5py',
                 'netCDF4', 'osgeo',
-                'xarray']
+                'cartopy']
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
 # get wradlib version
diff --git a/source/dev_guide.rst b/source/dev_guide.rst
@@ -3,7 +3,7 @@ Developer Guide
 
 Setup
 -----
-The section :doc:`installation` will provide you with detailed guidance on how to install :math:`\omega radlib` and the required dependencies for different operating systems (MS Windows, Linux, Mac OS). :math:`\omega radlib` |release| has been tested with the latest Anaconda Python on linux-64, osx-64 and MS Windows 32 and 64 versions.
+The section :doc:`installation` will provide you with detailed guidance on how to install :math:`\omega radlib` and the required dependencies for different operating systems (MS Windows, Linux, Mac OS). :math:`\omega radlib` |release| has been tested with the latest Anaconda Python on linux-64. It is available via `conda-forge` channel on linux-64, osx-64 and MS Windows 64 versions.
 
 As a developer, though, you should rather link into :math:`\omega radlib`'s version control. This way, it will be easier for you to track changes and to contribute your changes to :math:`\omega radlib`'s main respository (see next section). Just install `Git <https://git-scm.com/>`_, then clone the :math:`\omega radlib` repository to your local system by executing the following command in your shell: ``git clone https://github.com/wradlib/wradlib.git``. Do not forget to set the ``PYTHONPATH`` to point to the corresponding directory.
 
diff --git a/source/ide.rst b/source/ide.rst
@@ -1,5 +1,5 @@
-Integrated Development Environments for Python
-==============================================
+IDEs for Python
+===============
 
 Development Environments vs. Notebooks
 --------------------------------------
diff --git a/source/index.rst b/source/index.rst
@@ -11,7 +11,7 @@ wradlib: An Open Source Library for Weather Radar Data Processing
 :notebooks: {notebooks}
 :docs: {docs}
 
-The :math:`\omega radlib` project has been initiated in order facilitate the use of weather radar data as well as to provide a common platform for research on new algorithms. :math:`\omega radlib` is an open source library which is well documented and easy to use. It is written in the free programming language `Python <https://www.python.org>`_.
+The :math:`\omega radlib` project has been initiated in order facilitate the use of weather radar data as well as to provide a common platform for research on new algorithms. :math:`\omega radlib` is an open source library which is well documented and easy to use. It is written in the free programming language `Python <https://www.python.org>`_. As of version 1.3 :math:`\omega radlib` is Python 3 only.
 
 .. note:: Please cite :math:`\omega radlib` as *Heistermann, M., Jacobi, S., and Pfaff, T.: Technical Note: An open source library for processing weather radar data (wradlib), Hydrol. Earth Syst. Sci., 17, 863-871,* doi:`10.5194/hess-17-863-2013, 2013 <https://www.hydrol-earth-syst-sci.net/17/863/2013/hess-17-863-2013.pdf>`_
 
@@ -24,21 +24,81 @@ with high spatio-temporal resolution over large areas makes it an invaluable too
 
 This documentation is under steady development. It provides a complete library reference as well as a set of tutorials which will get you started in working with :math:`\omega radlib`.
 
+Documentation
+-------------
+
+**Installation**
+
+* :doc:`installation`
+* :doc:`docker`
+* :doc:`ide`
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :hidden:
+   :caption: Getting started
 
    installation
+   docker
+   ide
+
+**User Guide**
+
+* :doc:`user_guide`
+* :doc:`notebooks/fileio`
+* :doc:`Attenuation Correction <notebooks/attenuation/wradlib_attenuation>`
+* :doc:`Echo Classification <notebooks/classify>`
+* :doc:`notebooks/georeferencing`
+* :doc:`plotting`
+* :doc:`Interpolation <notebooks/interpolation/wradlib_ipol_example>`
+* :doc:`Rainfall Adjustment <notebooks/multisensor/wradlib_adjust_example>`
+* :doc:`notebooks/zonalstats/wradlib_zonalstats_classes`
+* :doc:`specials`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Tutorials & examples
+
    user_guide
-   notebooks/overview.ipynb
+   notebooks/fileio
+   Attenuation Correction <notebooks/attenuation/wradlib_attenuation>
+   Echo Classification <notebooks/classify>
+   notebooks/georeferencing
+   plotting
+   Interpolation <notebooks/interpolation/wradlib_ipol_example>
+   Rainfall Adjustment <notebooks/multisensor/wradlib_adjust_example>
+   notebooks/zonalstats/wradlib_zonalstats_classes
+   specials
+
+**Help & reference**
+
+* :doc:`reference`
+* :doc:`community`
+* :doc:`dev_guide`
+* :doc:`zreferences`
+* :doc:`release_notes`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Help & reference
+
    reference
+   community
    dev_guide
    zreferences
    release_notes
 
+License
+-------
+
+wradlib is available under the open source `MIT License`__.
+
+__ https://opensource.org/licenses/MIT
+
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-
diff --git a/source/jupyter.rst b/source/jupyter.rst
@@ -27,7 +27,7 @@ Once these conditions are met, you can open a notebook: Launch a console or bash
 If you installed :math:`\omega radlib` into a conda environment (as recommended :doc:`here <installation>`),
 you need to activate that environment first. Let's say you named the environment `wradlib`::
 
-    > activate wradlib
+    > conda activate wradlib
     > jupyter notebook
 
 Did you forget the name of the environment that contains wradlib? This way, you get an overview over all environments::
@@ -37,8 +37,8 @@ Did you forget the name of the environment that contains wradlib? This way, you
 which will give you something like (example output under Windows)::
 
     # conda environments
-    wradlib      C:\Anaconda2\envs\wradlib
-    root      *  C:\Anaconda2
+    wradlib      C:\Anaconda3\envs\wradlib
+    root      *  C:\Anaconda3
 
 In both cases, a browser window will open (typically at http://localhost:8888/tree) which will show the tree of the directory in which you started the jupyter notebook server. Just open any notebook by clicking. Code cells are executed by hitting ``Shift + Enter`` or by using the toolbar icons. It's pretty much self-explaining, and you'll soon get the hang of it.
 
diff --git a/source/plotting.rst b/source/plotting.rst
@@ -0,0 +1,12 @@
+Plotting
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   notebooks/visualisation/wradlib_plot_ppi_example
+   notebooks/visualisation/wradlib_plot_rhi_example
+   notebooks/visualisation/wradlib_plot_curvelinear_grids
+   notebooks/visualisation/wradlib_plot_ppi_xarray
+   notebooks/visualisation/wradlib_overlay
+   notebooks/visualisation/wradlib_overlay_cartopy
diff --git a/source/release_notes.rst b/source/release_notes.rst
@@ -5,13 +5,31 @@ Please note that :math:`\omega radlib` releases follow `semantic versioning <htt
 
 You can install the latest :math:`\omega radlib` release from PyPI via ``$ pip install wradlib`` or specific version via ``$ pip install wradlib==x.y.z``. The recommended installation process is described in :doc:`installation`.
 
-
 Bleeding Edge
 -------------
 
+Nothing, so far.
+
+Version 1.3.0
+-------------
+
 **Highlights**
 
-* added xarray-powered reader/writer for Cf/Radial and ODIM_H5
+* wradlib is considered Python3 only working with Python >= 3.6
+* xarray-powered reader/writer for Cf/Radial 1.X and 2.0 as well as ODIM_H5
+* xarray-powered plotting using DataArray via xarray-DataArray Accessor
+
+**New features**
+
+* creation of xarray DataArray from spherical coordinates and radar data
+* update test machinery to use pytest (mainly CI use)
+* correctly apply `semver`
+
+**Bugfixes**
+
+* beamblockage calculation, precisely detect clear or blocked beam
+* catch HTTPError in `test_radiosonde`, graceful skip test
+* `spherical_to_xyz` better aligns with input dimensions
 
 Version 1.2.0
 -------------
diff --git a/source/specials.rst b/source/specials.rst
@@ -0,0 +1,11 @@
+Specials
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   notebooks/beamblockage/wradlib_beamblock
+   notebooks/match3d/wradlib_match_workflow
+   notebooks/verification/wradlib_verify_example
+   notebooks/radolan
+   notebooks/recipes
diff --git a/source/user_guide.rst b/source/user_guide.rst
@@ -1,10 +1,9 @@
-User Guide
-==========
+Introduction
+============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    jupyter.rst
-   ide.rst
-   docker.rst
-   community.rst
+   notebooks/learnpython
+   notebooks/basics
