Merge pull request #303 from cerfacs-globc/add_dcsc_indices

ENH: large refactoring

.github/CONTRIBUTING.rst

@@ -1,5 +1,5 @@
-Welcome to icclim contribution guide
-------------------------------------
+icclim contribution guide
+-------------------------
 
 This document aim to guide you on how to contribute to icclim.
 Everyone is welcomed and contribution are appreciated!
@@ -10,7 +10,9 @@ Contents:
     #. :ref:`Add new standard indices`
     #. :ref:`Add new operators for user indices`
     #. :ref:`Improve icclim API`
+    #. :ref:`Other contributions`
 
+.. _Getting started:
 
 Getting started
 ===============
@@ -44,13 +46,15 @@ You can now:
 
 .. note::
     git commits should start with one of the keywords from:
-        - `ENH:` for enhancements and new features.
-        - `MAINT:` for maintenance, and refactoring.
-        - `DOC:` for documentation update.
-        - `FIX:` for bug fixes.
+        - ``ENH`` for enhancements and new features.
+        - ``MAINT`` for maintenance, and refactoring.
+        - ``DOC`` for documentation update.
+        - ``FIX`` for bug fixes.
 
     See `numpy's guide <https://numpy.org/doc/stable/dev/development_workflow.html#writing-the-commit-message>`_ for additional keywords.
 
+.. _Documentation contribution:
+
 Documentation contribution
 ==========================
 
@@ -83,13 +87,15 @@ First install it with pip. Then, in a separate terminal, cd into doc directory a
 By default it will serve the documentation on ``localhost://8000``.
 
 Additionally, icclim now has a logo that is displayed on github and readthedocs.
-Logos are stored in `/doc/source/_static/` directory.
+Logos are stored in ``/doc/source/_static/`` directory.
 The logos are svg images and the icclim version number is embed in them. Thus, they must be updated for each new icclim version.
-The `xyz__base.svg` files contains the placeholder `{{icclim.__version__}}` which is replaced in the `xyz__display.svg` files.
+The ``xyz__base.svg`` files contains the placeholder ``{{icclim.__version__}}`` which is replaced in the ``xyz__display.svg`` files.
 Fortunately, this version number update process is automated in our C.I. as github actions (see :ref:`Continuous integration`).
 However, if one wish to edit the logo manually, he/she will need to initialize git LFS on his/her local repository.
 Refer to `this guide <https://git-lfs.github.com/>` for what is git lfs and how to init it locally.
 
+.. _Add new standard indices:
+
 Add new standard indices
 ========================
 
@@ -148,6 +154,7 @@ This should not be an issue as icclim try to always enforce the latest xclim ver
 Then you have to bind the new index into icclim.
 This process is described in section `Existing index in xclim`_ above.
 
+.. _Add new operators for user indices:
 
 Add new operators for user indices
 ==================================
@@ -175,6 +182,8 @@ Once the binding is done, don't forget to add unit tests and to update the docum
 For the unit tests, you can add them in ``tests/unit_tests/test_user_indices.py``.
 For the documentation, you should add an explanation of the operator behavior in section ``user_index`` of ``doc/references/icclim_index_api.rst``.
 
+.. _Improve icclim API:
+
 Improve icclim API
 ==================
 
@@ -200,6 +209,7 @@ For post-processing steps:
     - At DataArray level, the changes should be done either in ``icclim/ecad_functions.py`` module or directly in xclim.
     - At Dataset level, you should probably edit ``icclim/main.py`` module.
 
+.. _Other contributions:
 
 Other contributions
 ===================

.github/workflows/ci.yml

@@ -22,9 +22,11 @@ jobs:
       - name: Install icclim and dev requirements (dev, test and doc)
         run: flit install --deps develop
       - name: call fun extractor
-        run: python ./tools/extract_icclim_funs.py src/icclim/_generated_api.py
+        run: python ./tools/extract_icclim_funs.py
       - name: run ruff format on generated module
-        run: ruff format src/icclim/_generated_api.py
+        run: |
+          ruff format src/icclim/_generated/
+          ruff check src/icclim/_generated/ --fix
       - name: create local ref
         run: |
           git fetch origin ${{ github.head_ref }}
@@ -37,7 +39,7 @@ jobs:
       - name: commit
         run: |
           # Stage the file, commit and push
-          git add src/icclim/_generated_api.py
+          git add src/icclim/_generated
           # Ignore error cases
           git commit -m "MAINT: Update generated API" || true
           git push origin ${{ github.head_ref }}

README.rst

@@ -68,7 +68,7 @@ For a detailed description of each ECA&D index, please visit: https://www.ecad.e
 ..
   Pytest Coverage Comment:Begin
 
-.. |coverage| image:: https://img.shields.io/badge/Coverage-86%25-green.svg
+.. |coverage| image:: https://img.shields.io/badge/Coverage-84%25-green.svg
         :target: https://github.com/cerfacs-globc/icclim/blob/master/README.rst#code-coverage
         :alt: Code coverage
 

doc/source/conf.py

@@ -1,4 +1,4 @@
-# noqa: INP001
+"""Sphinx configuration file for icclim documentation."""  # noqa: INP001
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -30,18 +30,39 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
+    # Finds sources from object description and generated highlighted standalone pages
     "sphinx.ext.viewcode",
+    # Enables parsing of numpy's style docstring
     "sphinx.ext.napoleon",
-    "sphinx.ext.autosectionlabel",
-    "sphinx.ext.autosummary",
+    # Allows to link to external ressources
     "sphinx.ext.intersphinx",
+    # Makes code example clickable
     "sphinx_codeautolink",
+    # make sphinx extension fetch LFS content
     "sphinx_lfs_content",
+    # Add copy button to code snippets
     "sphinx_copybutton",
+    # Add ipython directive
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
+    # Add notebook parsing
     "nbsphinx",
+    # Enable autoapi directives
+    "sphinx.ext.autodoc",
+    "autoapi.extension",
+]
+autoapi_generate_api_docs = False
+autoapi_dirs = ["../../src"]
+autoapi_root = "references/api"
+# autoapi_keep_files = True   # noqa: ERA001 , E501 (uncomment to generate the API and recomment after)
+autoapi_options = [
+    # "members",
+    # "undoc-members",
+    "private-members",
+    # "show-inheritance",
+    # "show-module-summary",
+    # "special-members",
+    "imported-members",
 ]
 
 autosectionlabel_maxdepth = 2

doc/source/dev/ci.rst

@@ -1,3 +1,5 @@
+.. _Continuous integration:
+
 ########################
  Continuous integration
 ########################
@@ -10,13 +12,14 @@ icclim continuous integration (CI) aims to assist development by:
    -  Making sure the documentation generation is functioning well.
 
 These goals are reached using multiple tools:
-   -  pre-commit CI enforce the code style (Black + flake8 + isort) is
-      followed by committing changes directly on new pull request and
-      blocking merge if necessary. The relevant file is
-      `.pre-commit-config.yaml`.
+   -  pre-commit CI enforces the code style rules. It is run on new pull requests
+      and may commit automatically to fix the source code.
+      If it fails to fix the code base, it woill block the PR from being merged.
+      The relevant configuration file is ``.pre-commit-config.yaml``.
 
-   -  readthedocs, which serve our documentation is also configured to
-      run the documentation generation on each new pull request.
+   -  readthedocs, it serves our documentation on https://icclim.readthedocs.io/en/stable/.
+      It is configured with ``.readthedocs.yml`` and runs the generation of the
+      documentation on each new pull request.
 
    -  github actions are used to run unit tests and report the results
-      in each pull request.
+      in each pull request. They are configured in ``../.github/workflows/ci.yml``

doc/source/dev/index.rst

@@ -1,3 +1,5 @@
+.. _dev:
+
 #############
  Development
 #############

doc/source/explanation/index.rst

@@ -1,3 +1,5 @@
+.. _explanation:
+
 #############
  Explanation
 #############

doc/source/how_to/recipes_custom.rst

@@ -1,12 +1,12 @@
 .. _custom_indices_recipes:
 
 ########################
- Custom indices recipes
+ User indices recipes
 ########################
 
 .. note::
 
-   Custom indices are deprecated. You should switch to
+   User indices are deprecated. You should switch to
    :ref:`generic_indices_recipes` API.
 
 .. code:: python
@@ -156,7 +156,7 @@ Get minimum temperature which is above zero Celsius and find its date.
 
    my_index_params = {
        "index_name": "my_index",
-       "calc_operation": "nb_events",  ### 'calc_operation': 'max_nb_consecutive_events'
+       "calc_operation": "nb_events",
        "logical_operation": "gt",
        "thresh": "p80",
        "var_type": "t",

doc/source/how_to/recipes_generic.rst

@@ -24,13 +24,13 @@ precipitation are above 3 mm/day.
 
 .. code:: python
 
-   # Equivalent to using `reasonable_temp = "<= 30 deg_C AND >= 20 deg_C"`
-   reasonable_temp = build_threshold("<= 30 deg_C") & build_threshold(">= 20 deg_C")
+   # Equivalent to using `okay_temp = "<= 30 deg_C AND >= 20 deg_C"`
+   okay_temp = build_threshold("<= 30 deg_C") & build_threshold(">= 20 deg_C")
    some_rain = icclim.build_threshold("> 3 mm/day")
 
    dataset = icclim.count_occurrences(
        in_files={
-           "tmax": {"study": data, "thresholds": reasonable_temp},
+           "tmax": {"study": data, "thresholds": okay_temp},
            "precip": {"study": data, "thresholds": some_rain},
        }
    )