Fix documentation

AUTHORS.md

@@ -1,11 +1,13 @@
-# Project contributors
+# Project Contributors
 
-GPM-API is available on [GitHub](https://github.com/ghiggi/gpm_api) and was created by following people.
+The following people have made contributions to this project:
 
-## Main Authors
+<!--- Use your GitHub account or any other personal reference URL --->
+<!--- If you wish to not use your real name, please use your github username --->
+<!--- The list should be alphabetical by last name if possible, with github usernames at the bottom  and the istitution --->
 
-- Gionata Ghiggi, GitHub: [@ghiggi](https://github.com/ghiggi), Email:  <[email protected]>
+<!--- See https://gist.github.com/djhoese/52220272ec73b12eb8f4a29709be110d for auto-generating parts of this list --->
 
-## Contributors (in order of contributions)
-
-- Randy Chase, GitHub: [@fhesze](https://github.com/dopplerchase), Email: <[email protected]>
+- [Gionata Ghiggi (ghiggi)](https://github.com/ghiggi) - EPFL
+- [Son Pham-Ba (sphamba)](https://github.com/sphamba) - EPFL
+- [Randy Chase (fhesze)](https://github.com/dopplerchase) - CIRA

docs/environment.yml

@@ -0,0 +1,18 @@
+name: build-doc-gpm-api
+channels:
+  - conda-forge
+dependencies:
+  - python>=3.9
+  - gpm-api
+  - ximage
+  - pyvista
+  - polars
+  - pandoc
+  - nbsphinx==0.8.9
+  - sphinx==5.1.1
+  - sphinx-book-theme==1.1.0
+  - sphinx-mdinclude==0.5.3
+  - sphinx-gallery
+  - pip
+  - pip:
+    - pycolorbar

docs/source/conf.py

@@ -21,8 +21,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "gpm_api"
-copyright = "LTE - Environmental Remote Sensing Lab - EPFL"
-author = "LTE - Environmental Remote Sensing Lab - EPFL"
+copyright = "Gionata Ghiggi"
+author = "Gionata Ghiggi"
 
 # -- General configuration ---------------------------------------------------
 
@@ -33,7 +33,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
-    "sphinx.ext.autosectionlabel",
+    # "sphinx.ext.autosectionlabel",
     "nbsphinx",
     "sphinx_mdinclude",
 ]
@@ -57,7 +57,15 @@
 html_title = "GPM-API"
 html_theme_options = {
     "repository_url": "https://github.com/ghiggi/gpm_api",
+    "repository_branch": "main",
     "use_repository_button": True,
+    "use_edit_page_button": True,
+    # "use_source_button": True,
+    "use_issues_button": True,
+    # "use_repository_button": True,
+    "use_download_button": True,
+    # "use_sidenotes": True,
+    "show_toc_level": 2,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/source/index.rst

@@ -29,6 +29,9 @@ Tutorials and Examples
    tutorials/download
 
 
+API Reference
+===============
+
 .. toctree::
    :maxdepth: 1
 

docs/source/installation.rst

@@ -5,158 +5,173 @@ Installation
 
 We define here two types of installation:
 
-- `Installation for standard users`_: for users who want to process data.
+- `Installation for standard users`_ : for users who want to process data.
 
 - `Installation for contributors`_: for contributors who want to enrich the project (eg. add a new reader).
 
-We recommend users and contributors to use a `Virtual environment`_ to install GPM-API.
+We recommend users and contributors to first set up a `Virtual Environment <#virtual_environment>`_ where to install GPM-API.
 
 
-Installation for standard users
-==================================
+.. _virtual_environment:
 
-pip-based installation
-..............................
+Virtual environment creation
+===============================
 
-GPM-API is available from the `Python Packaging Index (PyPI) <https://pypi.org/>`__ as follow:
+While not mandatory, utilizing a virtual environment when installing GPM-API is recommended.
 
+Using a virtual environment for installing packages provides isolation of dependencies,
+easier package management, easier maintenance, improved security, and improved development workflow.
 
-.. code-block:: bash
+Here below we provide two options to set up a virtual environment,
+using `venv <https://docs.python.org/3/library/venv.html>`__
+or `conda <https://docs.conda.io/en/latest/>`__ (recommended).
 
-   pip install gpm_api
+**With conda:**
 
+* Install `miniconda <https://docs.conda.io/en/latest/miniconda.html>`__
+  or `anaconda <https://docs.anaconda.com/anaconda/install/>`__
+  if you don't have it already installed.
 
-Dependencies
-============
+* Create the `gpm-api-py311` (or any other custom name) conda environment:
 
-GPM-API depends on the ``cartopy`` Python package, which relies on the `GEOS <https://libgeos.org/>`_ library for its installation.
+.. code-block:: bash
 
-Linux
-.....
+	conda create --name gpm-api-py311 python=3.11 --no-default-packages
 
-On Linux, prior to the installation of GPM-API, you can install GEOS using your package manager (e.g. ``apt install libgeos-dev``). Then, install ``gpm_api`` using ``pip`` (see above).
+* Activate the `gpm-api-py311` conda environment:
 
-Windows
-.......
+.. code-block:: bash
 
-On Windows, the simplest method is to install Cartopy from the `conda-forge <https://conda-forge.org/>`_ channel using for example
+	conda activate gpm-api-py311
 
-.. code-block:: bash
 
-   conda install cartopy>=0.20.0
+**With venv:**
 
-Alternatively, if you are not using ``conda`` as an environment manager, there are `unofficial already-build Cartopy wheels <https://www.lfd.uci.edu/~gohlke/pythonlibs/#cartopy>`_. Download the wheel corresponding to your system (see `naming scheme <https://docs.fileformat.com/compression/whl/>`_) and run
+* Windows: Create a virtual environment with venv:
 
 .. code-block:: bash
 
-   pip install cartopy-0.xx.x-cp3x-cp3xm-win_xxxxx.whl
+   python -m venv gpm-api-pyXXX
+   cd gpm-api-pyXXX/Scripts
+   activate
 
 
+* Mac/Linux: Create a virtual environment with venv:
 
+.. code-block:: bash
 
-Installation for contributors
-================================
+   virtualenv -p python3 gpm-api-pyXXX
+   source gpm-api-pyXXX/bin/activate
 
+.. _installation_standard:
 
-The latest GPM-API stable version is available on the GitHub repository `GPM-API <https://github.com/ghiggi/gpm_api>`_.
+Installation for standard users
+==================================
 
-Clone the repository from GitHub
-.........................................
+The latest GPM-API stable version is available
+on the `Python Packaging Index (PyPI) <https://pypi.org/project/gpm-api/>`__
+and on the `conda-forge channel <https://anaconda.org/conda-forge/gpm-api>`__.
 
-According to the `contributors guidelines <https://gpm-api.readthedocs.io/en/latest/contributors_guidelines.html>`__, you should first create a fork into your personal GitHub account.
+Therefore you can either install the package with pip or conda.
+Installation with conda is recommended, as GPM-API depends on `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__
+and `GEOS <https://libgeos.org/>`_ libraries, which can be difficult to install with pip.
 
+Please install the package in the virtual environment you created before !
 
-* Install a local copy of the forked repository:
+**With conda:**
 
 .. code-block:: bash
 
-    git clone https://github.com/<your-account>/gpm_api.git
-    cd gpm_api
-
+   conda install -c conda-forge gpm-api
 
 
-To install the project in editable mode :
-
-.. code-block:: bash
+.. note::
+   In alternative to conda, if you are looking for a lightweight package manager you could use `micromamba <https://micromamba.readthedocs.io/en/latest/>`__.
 
-	pip install -e ".[image,dev]"
+**With pip:**
 
+On Linux, prior to the installation of GPM-API, you can install GEOS using your package manager (e.g. ``apt install libgeos-dev``).
 
+Then, install API with:
 
-Install pre-commit code quality checking
-..............................................
+.. code-block:: bash
 
-After setting up your development environment, install the git
-pre-commit hook by executing the following command in the repository’s
-root:
+   pip install gpm-api
 
-.. code-block:: bash
 
-   pip install pre-commit
-   pre-commit install
+.. _installation_contributor:
 
+Installation for contributors
+================================
 
-The pre-commit hooks are scripts executed automatically in every commit
-to identify simple code quality issues. When an issue is identified
-(the pre-commit script exits with non-zero status), the hook aborts the
-commit and prints the error. Currently, GPM-API tests that the
-code to be committed complies with `black’s  <https://github.com/psf/black>`__ format style
-and the `ruff <https://github.com/charliermarsh/ruff>`__ linter.
+The latest GPM-API version is available on the GitHub repository `gpm_api <https://github.com/ghiggi/gpm_api>`_.
+You can install the package in editable mode, so that you can modify the code and see the changes immediately.
+Here below we provide the steps to install the package in editable mode.
 
-In case that the commit is aborted, you only need to run `black`and `ruff` through your code.
-This can be done by running ``black .`` and ``ruff check .`` or alternatively with ``pre-commit run --all-files``.
-The latter is recommended since it indicates if the commit contained any formatting errors (that are automatically corrected).
+Clone the repository from GitHub
+......................................
 
-.. note::
-	To maintain consitency, we use Black version `22.8.0` (as defined into `.pre-commit-config.yaml`). Make sure to stick to version.
+According to the ::ref:`contributors guidelines <contributor_guidelines>`,
+you should first
+`create a fork into your personal GitHub account <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`__.
 
+Then create a local copy of the repository you forked with:
 
+.. code-block:: bash
 
-Virtual environment
-==================================
+   git clone https://github.com/<your-account>/gpm_api.git
+   cd gpm_api
 
-While not mandatory, utilizing a virtual environment when installing GPM-API is recommended. Using a virtual environment for installing packages provides isolation of dependencies, easier package management, easier maintenance, improved security, and improved development workflow.
+Create the development environment
+......................................
 
+We recommend to create a dedicated conda environment for development purposes.
+You can create a conda environment (i.e. with python 3.11) with:
 
+.. code-block:: bash
 
-To set up a virtual environment, follow these steps :
+	conda create --name gpm-api-dev-py311 python=3.11 --no-default-packages
+	conda activate gpm-api-dev-py311
 
-* **With venv :**
+Install the GPM-API package dependencies
+............................................
 
-	* Windows: Create a virtual environment with venv:
+.. code-block:: bash
 
-		.. code-block:: bash
+	conda install --only-deps gpm-api
 
-		   python -m venv gpm-api-dev
-		   .\gpm-api-dev\Scripts\activate
 
+Install the GPM-API package in editable mode
+................................................
 
-	* Mac/Linux: Create a virtual environment with venv:
+Install the GPM-API package in editable mode by executing the following command in the GPM-API repository's root:
 
-		.. code-block:: bash
+.. code-block:: bash
 
-		   virtualenv -p python3 gpm-api-dev
-		   source gpm-api-dev/bin/activate
+	pip install -e ".[dev]"
 
 
+Install pre-commit code quality checks
+..............................................
 
-* **With conda:**
+Install the pre-commit hook by executing the following command in the GPM-API repository's root:
 
-	* Create the `gpm-api-dev` (or anay other name) conda environment:
+.. code-block:: bash
 
-		.. code-block:: bash
+   pre-commit install
 
-			conda create --name gpm-api-dev python=3.9 --no-default-packages
 
-	* Activate the GPM-API conda environment:
+Pre-commit hooks are automated scripts that run during each commit to detect basic code quality issues.
+If a hook identifies an issue (signified by the pre-commit script exiting with a non-zero status), it halts the commit process and displays the error messages.
 
-		.. code-block:: bash
+.. note::
+	The versions of the software used in the pre-commit hooks is specified in the `.pre-commit-config.yaml <https://github.com/ghiggi/gpm_api/blob/main/.pre-commit-config.yaml>`__ file. This file serves as a configuration guide, ensuring that the hooks are executed with the correct versions of each tool, thereby maintaining consistency and reliability in the code quality checks.
 
-			conda activate gpm-api-dev
+Further details about pre-commit hooks can be found in the Contributors Guidelines, specifically in the provided in the :ref:`Code quality control <code_quality_control>` section.
 
 
 Run GPM-API on Jupyter Notebooks
-==================================
+=====================================
 
 If you want to run GPM-API on a `Jupyter Notebook <https://jupyter.org/>`__,
 you have to take care to set up the IPython kernel environment where GPM-API is installed.
@@ -165,6 +180,6 @@ For example, if your conda/virtual environment is named `gpm-api-dev`, run:
 
 .. code-block:: bash
 
-    python -m ipykernel install --user --name=gpm-api-dev
+   python -m ipykernel install --user --name=gpm-api-dev
 
 When you will use the Jupyter Notebook, by clicking on `Kernel` and then `Change Kernel`, you will be able to select the `gpm-api-dev` kernel.