Doc: Move doc to root

icclim/doc/source/conf.py → doc/source/conf.py

@@ -10,9 +10,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("."))
 
 
 # -- Project information -----------------------------------------------------

icclim/doc/source/explanation/index.rst → doc/source/explanation/index.rst

@@ -1,4 +1,5 @@
 .. _explanation:
+
 Explanation
 ===========
 

doc/source/how_to/index.rst

@@ -0,0 +1,16 @@
+.. _how_to:
+
+How to ...
+==========
+
+| These documents should serve as recipes to solve specific issues, they should answer "How to ..." questions.
+| They are meant to be used by user who already have some knowledge of icclim and want recipes to solve specific problems.
+
+To grasp the basic usage of icclim, you may consider following :ref:`tutorials` first.
+To find more in depth technical knowledge see :ref:`references`.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    Use icclim through OCGIS <ocgis>

doc/source/index.rst

@@ -0,0 +1,44 @@
+.. icclim documentation master file, created by
+   sphinx-quickstart on Tue Dec 14 14:42:00 2021.
+
+.. _diataxis: https://diataxis.fr/
+.. _xclim: https://xclim.readthedocs.io/en/stable/
+.. _xarray: https://xarray.pydata.org/en/stable/
+.. _dask: https://dask.org/
+.. _NumPy: http://www.numpy.org
+.. _netCDF: http://www.unidata.ucar.edu/software/netcdf
+
+Icclim's documentation
+======================
+Icclim (Index Calculation for CLIMate) is a Python library for computing a number of climate indices.
+It built on a open source stack made of `xclim`_, `xarray`_, `dask`_ and of course `NumPy`_.
+
+.. note::
+
+   Icclim documentation is currently under construction. We try to follow the `diataxis`_ principles to build a comprehensive user focused doc.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   tutorials/index
+   how_to/index
+   references/index
+   explanation/index
+
+
+A few notes about Icclim
+------------------------
+1. Input datasets must be compliant to the `CF convention <https://cfconventions.org/>`_.
+2. Currently, *Icclim* doesn't support spatial subsetting, i.e. it processes whole spatial area.
+3. *Icclim* works with unsecured OPeNDAP datasets as well.
+4. Icclim developer repository can be found here: `<https://github.com/cerfacs-globc/icclim>`_
+
+Contacts
+--------
+Add If you encounter a bug or an issue while using icclim, don't hesitate to open a ticket on our `github <https://github.com/cerfacs-globc/icclim/issues>`_.
+
+Maintainers
+~~~~~~~~~~~
+- Christian Page, `@pagecp <https://github.com/pagecp/>`_ <christian.page[at]cerfacs.fr>
+   - Abel Aoun, `@bzah <https://github.com/bzah>`_ <abel.aoun[at]cerfacs.fr>

icclim/doc/source/references/index.rst → doc/source/references/index.rst

@@ -1,4 +1,5 @@
 .. _references:
+
 References
 ==========
 .. toctree::

doc/source/references/release_notes.rst

@@ -0,0 +1,36 @@
+Release history
+===============
+
+5.0.0rc2
+--------
+
+* Make HD17 expect tas instead of tas_min
+
+5.0.0
+-----
+We fully rewrote Icclim to benefit from Xclim, Xarray, Numpy and Dask.
+A lot of effort has been to minimize the API changes.
+Thus for all scripts using a former version of icclim updating to this new version should be smooth.
+
+In fact, we made a few improvements on the API
+    - We replaced everywhere the french singular word "indice" by the proper english "index". You should get a warning if you still use "indice" such as in "indice_name".
+    - When ``save_percentile`` is used, the resulting percentiles are saved within the same netcdf file as the climate index.
+    - Most of the keywords (such as slice_mode, index_name, are now case insensitive to avoid unnecessary errors.
+    - When ``in_files`` is a list the netcdf are combined to lookup them all the necessary variables.
+    - When multiple variables are stored into a single ``in_files``, there is no more need to use a list.
+    - ``in_files`` parameter can now be a Xarray.Dataset directly. In that case, ``out_file`` is ignored.
+    - ``var_name`` parameter is now optional for ECA&D indices, icclim will try to look for a valid variable depending on the index wanted
+    - ``transfer_limit_Mbytes`` parameter is now used to adjust how Dask should chunk the dataset.
+    - The output of ``icclim.index()`` is now the resulting Xarray Dataset of the index computation. ``out_file`` can still be used to write output to a netcdf.
+    - `logs_verbosity` parameter can now control how much logs icclim will produce. The possible values are ``{"HIGH", "LOW", "SILENT"}``.
+
+Additionally
+    - Icclim C code has also been removed. This makes the installation and maintenance much easier.
+    - Climate indices metadata has been enriched with Xclim metadata.
+    - With this rewrite a few indices were fixed as they were giving improper results.
+    - Performances have been significantly improved, especially thanks to Dask.
+
+Notes
+~~~~~
+It is highly recommended to use Dask distributed scheduler to fully benefit from the performance improvements of version
+5.0.0.

icclim/doc/source/tutorials/index.rst → doc/source/tutorials/index.rst

@@ -1,4 +1,5 @@
 .. _tutorials:
+
 Tutorials
 =========