From 1d2dce5862c23496e943e3990bb680555558589f Mon Sep 17 00:00:00 2001 From: Son Pham-Ba Date: Mon, 17 Jul 2023 14:27:17 +0200 Subject: [PATCH 1/7] doc: add citation.cff --- CITATION.cff | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 CITATION.cff diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 00000000..7c825e6b --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,17 @@ +cff-version: 1.2.0 +title: GPM-API +message: >- + If you use this software, please cite it using the + metadata from this file. +type: software +authors: + - given-names: Gionata + family-names: Ghiggi + email: gionata.ghiggi@epfl.ch + affiliation: EFPL + orcid: 'https://orcid.org/0000-0002-0818-0865' + - given-names: Randy + family-names: Chase + email: randy.chase12@gmail.com +repository-code: 'https://github.com/ghiggi/gpm_api' +license: MIT From df05c01b92ee4e147a6d60b8f5cb3a8f6d5d3c17 Mon Sep 17 00:00:00 2001 From: Son Pham-Ba Date: Mon, 17 Jul 2023 15:04:22 +0200 Subject: [PATCH 2/7] doc: add installation instructions --- docs/source/installation.rst | 150 ++++++++++++++++++++++++++++++++++- 1 file changed, 147 insertions(+), 3 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 583bd949..908be760 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,5 +1,149 @@ -============ +========================= Installation -============ +========================= -todo + +We define here two types of installation: + +- `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. + + +Installation for standard users +================================== + +pip-based installation +.............................. + +GPI-API is available from the `Python Packaging Index (PyPI) `__ as follow: + + +.. code-block:: bash + + pip install gpm_api + + +Prior installation of GPM-API, to avoid `GEOS `_ library version incompatibilities when +installing the Cartopy package, we highly suggest to install first Cartopy using ``conda install cartopy>=0.21.0``. +Alternatively, on Linux, you can install GEOS using your package manager (e.g. ``apt install libgeos-dev``). + + + +Installation for contributors +================================ + + +The latest GPI-API stable version is available on the GitHub repository `GPI-API `_. + +Clone the repository from GitHub +......................................... + +According to the `contributors guidelines `__, you should first create a fork into your personal GitHub account. + + +* Install a local copy of the forked repository: + +.. code-block:: bash + + git clone https://github.com//gpm_api.git + cd gpm_api + + + +To install the project in editable mode : + +.. code-block:: bash + + pip install -e .[image,dev] + + + +Install pre-commit code quality checking +.............................................. + +After setting up your development environment, install the git +pre-commit hook by executing the following command in the repository’s +root: + +.. code-block:: bash + + pip install pre-commit + pre-commit install + + +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, GPI-API tests that the +code to be committed complies with `black’s `__ format style +and the `ruff `__ linter. + +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). + +.. note:: + To maintain consitency, we use Black version `22.8.0` (as defined into `.pre-commit-config.yaml`). Make sure to stick to version. + + + +Virtual environment +================================== + +While not mandatory, utilizing a virtual environment when installing GPI-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. + + + +To set up a virtual environment, follow these steps : + +* **With venv :** + + * Windows: Create a virtual environment with venv: + + .. code-block:: bash + + python -m venv gpm-api-dev + cd gpm-api-dev/Scripts + activate + + + * Mac/Linux: Create a virtual environment with venv: + + .. code-block:: bash + + virtualenv -p python3 gpm-api-dev + source gpm-api-dev/bin/activate + + + +* **With conda:** + + * Create the `gpm-api-dev` (or anay other name) conda environment: + + .. code-block:: bash + + conda create --name gpm-api-dev python=3.9 --no-default-packages + + * Activate the GPI-API conda environment: + + .. code-block:: bash + + conda activate gpm-api-dev + + +Run GPI-API on Jupyter Notebooks +================================== + +If you want to run GPI-API on a `Jupyter Notebook `__, +you have to take care to set up the IPython kernel environment where GPI-API is installed. + +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 + +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. From 53eab5051dfddb4a9b0135f30f7fcbaaeb7c21d1 Mon Sep 17 00:00:00 2001 From: Son Pham-Ba Date: Mon, 24 Jul 2023 16:26:03 +0200 Subject: [PATCH 3/7] doc: install instructions (also windows) --- docs/source/installation.rst | 47 ++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 13 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 908be760..a9b9818b 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -18,7 +18,7 @@ Installation for standard users pip-based installation .............................. -GPI-API is available from the `Python Packaging Index (PyPI) `__ as follow: +GPM-API is available from the `Python Packaging Index (PyPI) `__ as follow: .. code-block:: bash @@ -26,9 +26,31 @@ GPI-API is available from the `Python Packaging Index (PyPI) pip install gpm_api -Prior installation of GPM-API, to avoid `GEOS `_ library version incompatibilities when -installing the Cartopy package, we highly suggest to install first Cartopy using ``conda install cartopy>=0.21.0``. -Alternatively, on Linux, you can install GEOS using your package manager (e.g. ``apt install libgeos-dev``). +Dependencies +============ + +GPM-API depends on the ``cartopy`` Python package, which relies on the `GEOS `_ library for its installation. + +Linux +..... + +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). + +Windows +....... + +On Windows, the simplest method is to install Cartopy from the `conda-forge `_ channel using for example + +.. code-block:: bash + + conda install cartopy>=0.20.0 + +Alternatively, if you are not using ``conda`` as an environment manager, there are `unofficial already-build Cartopy wheels `_. Download the wheel corresponding to your system (see `naming scheme `_) and run + +.. code-block:: bash + + pip install cartopy-0.xx.x-cp3x-cp3xm-win_xxxxx.whl + @@ -36,7 +58,7 @@ Installation for contributors ================================ -The latest GPI-API stable version is available on the GitHub repository `GPI-API `_. +The latest GPM-API stable version is available on the GitHub repository `GPM-API `_. Clone the repository from GitHub ......................................... @@ -77,7 +99,7 @@ root: 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, GPI-API tests that the +commit and prints the error. Currently, GPM-API tests that the code to be committed complies with `black’s `__ format style and the `ruff `__ linter. @@ -93,7 +115,7 @@ The latter is recommended since it indicates if the commit contained any formatt Virtual environment ================================== -While not mandatory, utilizing a virtual environment when installing GPI-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. +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. @@ -106,8 +128,7 @@ To set up a virtual environment, follow these steps : .. code-block:: bash python -m venv gpm-api-dev - cd gpm-api-dev/Scripts - activate + .\gpm-api-dev\Scripts\activate * Mac/Linux: Create a virtual environment with venv: @@ -127,18 +148,18 @@ To set up a virtual environment, follow these steps : conda create --name gpm-api-dev python=3.9 --no-default-packages - * Activate the GPI-API conda environment: + * Activate the GPM-API conda environment: .. code-block:: bash conda activate gpm-api-dev -Run GPI-API on Jupyter Notebooks +Run GPM-API on Jupyter Notebooks ================================== -If you want to run GPI-API on a `Jupyter Notebook `__, -you have to take care to set up the IPython kernel environment where GPI-API is installed. +If you want to run GPM-API on a `Jupyter Notebook `__, +you have to take care to set up the IPython kernel environment where GPM-API is installed. For example, if your conda/virtual environment is named `gpm-api-dev`, run: From f75e58c0cd23e8caa4aca3456be3b38db739dbda Mon Sep 17 00:00:00 2001 From: Son Pham-Ba Date: Mon, 24 Jul 2023 16:51:39 +0200 Subject: [PATCH 4/7] doc: add quote to pip install "." --- docs/source/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index a9b9818b..025bd4a7 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -79,7 +79,7 @@ To install the project in editable mode : .. code-block:: bash - pip install -e .[image,dev] + pip install -e ".[image,dev]" From d776c7c0c2c24399d60fa950e75691de56abc9bc Mon Sep 17 00:00:00 2001 From: Gionata Ghiggi Date: Mon, 24 Jul 2023 22:12:45 +0200 Subject: [PATCH 5/7] Update CITATION.cff --- CITATION.cff | 1 - 1 file changed, 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index 7c825e6b..b99c8809 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -10,7 +10,6 @@ authors: email: gionata.ghiggi@epfl.ch affiliation: EFPL orcid: 'https://orcid.org/0000-0002-0818-0865' - - given-names: Randy family-names: Chase email: randy.chase12@gmail.com repository-code: 'https://github.com/ghiggi/gpm_api' From 94e22208b4efe5145587077b8cb2949ee8a97083 Mon Sep 17 00:00:00 2001 From: Gionata Ghiggi Date: Mon, 24 Jul 2023 22:12:49 +0200 Subject: [PATCH 6/7] Update CITATION.cff --- CITATION.cff | 1 - 1 file changed, 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index b99c8809..1ebde037 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -11,6 +11,5 @@ authors: affiliation: EFPL orcid: 'https://orcid.org/0000-0002-0818-0865' family-names: Chase - email: randy.chase12@gmail.com repository-code: 'https://github.com/ghiggi/gpm_api' license: MIT From dc00dec7a11ccda4b508aa5350145a8f8319872c Mon Sep 17 00:00:00 2001 From: Gionata Ghiggi Date: Mon, 24 Jul 2023 22:12:55 +0200 Subject: [PATCH 7/7] Update CITATION.cff --- CITATION.cff | 1 - 1 file changed, 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index 1ebde037..10be5d32 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -10,6 +10,5 @@ authors: email: gionata.ghiggi@epfl.ch affiliation: EFPL orcid: 'https://orcid.org/0000-0002-0818-0865' - family-names: Chase repository-code: 'https://github.com/ghiggi/gpm_api' license: MIT