DOC|MAINT: Format doc using rstfmt

Unfortunately rstfmt is not well maintained and some directives
are not supported.
This means we need to manually comment unknown directives, run
the formatter and uncomment them.
This is only suited for a one time formatting as I did here.

doc/source/dev/ci.rst

@@ -1,15 +1,22 @@
-Continuous integration
-======================
+########################
+ Continuous integration
+########################
 
 icclim continuous integration (CI) aims to assist development by:
-    - Avoiding introducing bugs in the code base.
-    - Ensuring all new code follow the same code style.
-    - Measuring how much icclim code base is tested by automated unit tests. This is known as code coverage.
-    - Making sure the documentation generation is functioning well.
+   -  Avoiding introducing bugs in the code base.
+   -  Ensuring all new code follow the same code style.
+   -  Measuring how much icclim code base is tested by automated unit
+      tests. This is known as code coverage.
+   -  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`.
-    - readthedocs, which serve our documentation is also configured to run the documentation generation on each new pull request.
-    - github actions are used to run unit tests and report the results in each pull request.
+   -  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`.
+
+   -  readthedocs, which serve our documentation is also configured to
+      run the documentation generation on each new pull request.
+
+   -  github actions are used to run unit tests and report the results
+      in each pull request.

doc/source/dev/index.rst

@@ -1,12 +1,14 @@
-Development
-===========
+#############
+ Development
+#############
 
-Here are some guidelines for those who which to contribute to icclim development.
+Here are some guidelines for those who which to contribute to icclim
+development.
 
 .. toctree::
-    :maxdepth: 2
-    :caption: Contents:
+   :maxdepth: 2
+   :caption: Contents:
 
-    release_process
-    ci
-    contributing
+   release_process
+   ci
+   contributing

doc/source/dev/release_process.rst

@@ -1,65 +1,88 @@
-Release process
-===============
-
-Automatic Release
-+++++++++++++++++
-
-As of icclim 6.6.0, a github action (`.github/workflows/publish-to-pypi.yml`) publishes
-icclim to pypi whenever a (github release)[https://github.com/cerfacs-globc/icclim/releases]
-is published.
-This github action requires a manual approuval.
-A dedicated `release` github environment has been created to manage the permission for this
+#################
+ Release process
+#################
+
+*******************
+ Automatic Release
+*******************
+
+As of icclim 6.6.0, a github action
+(`.github/workflows/publish-to-pypi.yml`) publishes icclim to pypi
+whenever a (github
+release)[https://github.com/cerfacs-globc/icclim/releases] is published.
+This github action requires a manual approuval. A dedicated `release`
+github environment has been created to manage the permission for this
 github action.
 
 Then an automatic process on conda-forge pick the new release from pypi,
-create a pull request on icclim-feedstock and wait for our review and approval to
-publish the release to conda-forge.
+create a pull request on icclim-feedstock and wait for our review and
+approval to publish the release to conda-forge.
 
 Hence, the process is as follow:
 
 #. Merge everything on icclim master branch
-#. Create a (github release)[https://github.com/cerfacs-globc/icclim/releases]
+#. Create a (github
+   release)[https://github.com/cerfacs-globc/icclim/releases]
 #. Wait for the github action to build the package
 #. Approve the github action to release to pypi
 #. Wait for conda-forge to create a PR on icclim-feedstock
 #. Edit and approve PR on icclim-feedstock
 
-Manual release (outdated)
-+++++++++++++++++++++++++
+***************************
+ Manual release (outdated)
+***************************
 
 The Automatic approach
 
 #. Make sure all tests pass.
+
 #. Create and checkout a release branch.
+
 #. Update version number of icclim in ``src/icclim/__init__.py``.
+
 #. Update release notes in ``doc/source/references/release_notes.rst``.
+
 #. Merge release branch to master with a PR.
+
 #. Clean dist directory content.
+
 #. Create wheel file on master and source archive.
 
-    .. code-block:: sh
+      .. code:: sh
 
-        python3 -m build
+         python3 -m build
 
 #. Upload to pypi.
 
-    .. code-block:: sh
+      .. code:: sh
+
+         flit publish
+
+#. Update conda-forge feedstock at
+   https://github.com/conda-forge/icclim-feedstock
+
+      The recipe `recipe/meta.yml` must be updated:
+         -  Fork the repository in with your own account.
+
+         -  Update icclim version number at the top.
+
+         -  Update `source.sha256` value with the tar.gz sha256.
+               You can get the tar.gz hash from `pypi
+               <https://pypi.org/project/icclim/#files>`_ using `view
+               hashes` link.
+
+         -  Add any new dependency in `requirements`.
 
-       flit publish
+         -  Create a pull request with these changes, targeting the main
+            fork on main branch
 
-#. Update conda-forge feedstock at https://github.com/conda-forge/icclim-feedstock
+         -  Wait for the CI feedback and correct things if needed.
 
-    The recipe `recipe/meta.yml` must be updated:
-        - Fork the repository in with your own account.
-        - Update icclim version number at the top.
-        - Update `source.sha256` value with the tar.gz sha256.
-            You can get the tar.gz hash from `pypi <https://pypi.org/project/icclim/#files>`_ using `view hashes` link.
-        - Add any new dependency in `requirements`.
-        - Create a pull request with these changes, targeting the main fork on main branch
-        - Wait for the CI feedback and correct things if needed.
-        - Merge the pull request
+         -  Merge the pull request
 
 #. Update `icclim github release <https://github.com/cerfacs-globc/icclim/releases>`_
-    - You should add a tag similar to the new version number.
-    - You should enter a short description of the changes, with a highlight on breaking changes.
-    - There is no need to fill the assets with anything as the release assets are already on conda-forge and pypi.
+      -  You should add a tag similar to the new version number.
+      -  You should enter a short description of the changes, with a
+         highlight on breaking changes.
+      -  There is no need to fill the assets with anything as the
+         release assets are already on conda-forge and pypi.

doc/source/explanation/4.2.x_installation.rst

@@ -1,12 +1,15 @@
-Install icclim 4.2 and under (outdated version)
-===============================================
+#################################################
+ Install icclim 4.2 and under (outdated version)
+#################################################
 
-For a version before 5.0.0, to run icclim you first need to compile our C library.
+For a version before 5.0.0, to run icclim you first need to compile our
+C library.
 
-The last version where this was needed is `4.2.20 <https://github.com/cerfacs-globc/icclim/tree/4.2.20>`_
+The last version where this was needed is `4.2.20
+<https://github.com/cerfacs-globc/icclim/tree/4.2.20>`_
 
 #. Compile the C code:
-    - `gcc -fPIC -g -c -Wall ./icclim/libC.c -o ./icclim/libC.o`
-    - `gcc -shared -o ./icclim/libC.so ./icclim/libC.o`
+      -  `gcc -fPIC -g -c -Wall ./icclim/libC.c -o ./icclim/libC.o`
+      -  `gcc -shared -o ./icclim/libC.so ./icclim/libC.o`
 
 #. Install icclim: `python setup.py install --user`