From 3ad8422b628ee6aa558d2ec4c3c3fb5e1e4770a4 Mon Sep 17 00:00:00 2001 From: mattijn Date: Thu, 1 Oct 2020 08:58:17 +0200 Subject: [PATCH 1/4] improve toml file --- pyproject.toml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 5a83850..c48cb76 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,12 +1,13 @@ [build-system] -requires = ["flit"] -build-backend = "flit.buildapi" +requires = ["flit_core >=2,<4"] +build-backend = "flit_core.buildapi" [tool.flit.metadata] module = "delft3dfmpy" author = "Deltares - HKV" -author-email = "" -home-page = "https://github.com/openearth/delft3dfmpy/" +home-page = "https://github.com/openearth/delft3dfmpy" +classifiers = ["License :: OSI Approved :: MIT License"] +description-file = "README.rst" requires = [ "geopandas", "rasterio", @@ -24,8 +25,7 @@ requires = [ "hkvsobekpy" ] keywords = "hydraulics hydrology data-science delft3dfm deltares hkv hydamo" -description-file = "README.rst" -classifiers = ["License :: MIT License"] +requires-python = ">=3.6" [tool.flit.metadata.requires-extra] dev = [ @@ -37,4 +37,4 @@ dev = [ "watchdog", "coverage", "Sphinx" -] \ No newline at end of file +] From 07e0de0dbaa3080fcd6bc51b3176bdbc84030005 Mon Sep 17 00:00:00 2001 From: mattijn Date: Thu, 1 Oct 2020 14:26:14 +0200 Subject: [PATCH 2/4] improve readme.rst for IDE and contributions --- README.rst | 61 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 48 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index a31466d..08f3301 100644 --- a/README.rst +++ b/README.rst @@ -36,16 +36,29 @@ Features Installation ------------ -By the following procedure you can install the delft3dfmpy module: +By the following procedure you can install the ``delft3dfmpy`` module. Remember that this requires an environment with multiple packages not included within ``delft3dfmpy``. +And depending on the Integrated Development Environment (IDE) additional registration of this new environment. + +If you do NOT have a correct environment or IDE for installation of ``delft3dfmpy``, prepare these first with the instructions below before installing the python package ``delft3dfmpy``. + + +Python package ``delft3dfmpy`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +1. Install the Python package ``delft3dfmpy`` directly, by executing the following command in an Anaconda Prompt + + ``python -m pip install git+https://github.com/openearth/delft3dfmpy.git`` + +2. If the command prompt states ``Successfully built delft3dfmpy`` then installation is succesful. + Environment Preparation ^^^^^^^^^^^^^^^^^^^^^^^ -Prepare an environment with the correct dependencies for delft3dfmpy +Prepare an environment with the correct dependencies for ``delft3dfmpy``. + 1. Install a Anaconda or Minoconda Python distribution: https://www.anaconda.com/products/individual https://docs.conda.io/en/latest/miniconda.html - 2. Save the content of https://raw.githubusercontent.com/openearth/delft3dfmpy/master/environment.yml and store this in a local file named ``environment.yml`` 3. Open Ananconda prompt and enter the directory where the ``envrionment.yml`` from step 2 is stored. @@ -62,13 +75,23 @@ Prepare an environment with the correct dependencies for delft3dfmpy You now have a correct and activated environment for installation of the ``delft3dfmpy`` Python package -Python package ``delft3dfmpy`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. Install the Python package ``delft3dfmpy`` directly, by executing the following command in the opened command prompt. - ``python -m pip install git+https://github.com/openearth/delft3dfmpy.git`` +Envrionment Integration in your IDE +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Integration of the prepared envrionment depends on the IDE of usage. Here we mention briefly some options for the user: +1. For a new instance of Jupyter within the activated environment: + + Using Notebook + ``conda install -c conda-forge notebook`` + or using JupyterLab + ``conda install -c conda-forge jupyterlab`` + +2. To register the newly created environment as a new kernel for Jupyter (Notebook or JupyterLab): + + ``python -m ipykernel install --user --name=delft3dfmpy + +3. No extra actions are required for PyCharm, Spyder or VSCode + Python extension. -2. If the command prompt states ``Successfully built delft3dfmpy`` then installation is succesful. Usage ----- @@ -81,14 +104,26 @@ The usage is best described by the example notebook: https://github.com/openeart Contribution ------------ -Contributions are much welcome for the documentation, missing but desirable features and bugs. The code and development happens in this GitHub repository: https://github.com/openearth/delft3dfmpy. +Contributions are much welcome for documentation, desirable features and bugs. The code and development happens in this GitHub repository: https://github.com/openearth/delft3dfmpy. For contributions, use the following guidelines: -1. Fork the project on GitHub, clone the fork to your Operating System and open the repository as folder/workspace in your favorite IDE (eg. VSCode + Python extension). +1. Fork the project on GitHub and clone the fork to your Operating System. + +2. Make sure you have installed and activated the environment as is described above. + +3. ``delft3dfmpy`` uses ``flit`` to to build, package and publish the project. To install the development dependencies and register the cloned fork as a Python package do the following fo: + + From an elevated Anaconda Prompt (run as Administrator) within the activated ``delft3dfmpy`` environment do: + ``conda install -c conda-forge flit`` + ``flit install --deps develop --symlink + + This installs the development dependencies and creates a symbolic link in the Python site-packages folder of the activated environment. + +4. Open the repository as folder/workspace in your favorite IDE (eg. VSCode + Python extension) -2. Make your contributions and test the changes locally. +5. Make your contributions and test the changes locally. -3. Once satisfied, push your changes as a new branch to your fork and create a Pull Request to the original repository. +6. Once satisfied, push your changes as a new branch to your fork and create a Pull Request to the original repository. -4. A maintainer on the main GitHub repository will review your PR and guide the merging process. +7. A maintainer on the main GitHub repository will review your PR and guide the merging process. From f4cf477e6595ef1b341e6c1ec082442bde0a5eec Mon Sep 17 00:00:00 2001 From: mattijn Date: Thu, 1 Oct 2020 14:39:16 +0200 Subject: [PATCH 3/4] fix some styling --- README.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index 08f3301..58f9490 100644 --- a/README.rst +++ b/README.rst @@ -36,10 +36,9 @@ Features Installation ------------ -By the following procedure you can install the ``delft3dfmpy`` module. Remember that this requires an environment with multiple packages not included within ``delft3dfmpy``. -And depending on the Integrated Development Environment (IDE) additional registration of this new environment. +The package ``delft3dfmpy`` requires you to have (a) environment with required dependencies and (b) an Integrated Development Envrionment (IDE) that can access this envrionment. -If you do NOT have a correct environment or IDE for installation of ``delft3dfmpy``, prepare these first with the instructions below before installing the python package ``delft3dfmpy``. +Please meet these two conditions first with instructions below before installing the Python package ``delft3dfmpy``. Python package ``delft3dfmpy`` @@ -79,24 +78,28 @@ Prepare an environment with the correct dependencies for ``delft3dfmpy``. Envrionment Integration in your IDE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Integration of the prepared envrionment depends on the IDE of usage. Here we mention briefly some options for the user: + 1. For a new instance of Jupyter within the activated environment: Using Notebook + ``conda install -c conda-forge notebook`` + or using JupyterLab + ``conda install -c conda-forge jupyterlab`` 2. To register the newly created environment as a new kernel for Jupyter (Notebook or JupyterLab): - ``python -m ipykernel install --user --name=delft3dfmpy - + ``python -m ipykernel install --user --name=delft3dfmpy`` + 3. No extra actions are required for PyCharm, Spyder or VSCode + Python extension. Usage ----- -Activate the created environment in an (anaconda) command prompt (conda activate delft3dfmpy) before running your notebook or script. A jupyter notebook or command prompt for the environment can also be launched from the Anaconda Navigator. +Activate the created environment in an (Anaconda) command prompt (``conda activate delft3dfmpy``) before running your notebook or script. A Jupyter notebook or command prompt for the environment can also be launched from the Anaconda Navigator. For more information on how to use environments, see: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html The usage is best described by the example notebook: https://github.com/openearth/delft3dfmpy/blob/master/notebooks/Usage_introduction_coupled_RRFM.ipynb @@ -112,11 +115,13 @@ For contributions, use the following guidelines: 2. Make sure you have installed and activated the environment as is described above. -3. ``delft3dfmpy`` uses ``flit`` to to build, package and publish the project. To install the development dependencies and register the cloned fork as a Python package do the following fo: +3. Delft3dfmpy uses ``flit`` to to build, package and publish the project. To install the development dependencies and register the cloned fork as a Python package for development purposes do the following: + + From an elevated Anaconda Prompt (run as Administrator) within the activated ``delft3dfmpy`` environment: - From an elevated Anaconda Prompt (run as Administrator) within the activated ``delft3dfmpy`` environment do: ``conda install -c conda-forge flit`` - ``flit install --deps develop --symlink + + ``flit install --deps develop --symlink`` This installs the development dependencies and creates a symbolic link in the Python site-packages folder of the activated environment. From d8b62b3d0fbb01101e7f9ae8ad0ff553c1149931 Mon Sep 17 00:00:00 2001 From: mattijn Date: Thu, 1 Oct 2020 15:01:23 +0200 Subject: [PATCH 4/4] be more clear on IDE --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 58f9490..6a4d665 100644 --- a/README.rst +++ b/README.rst @@ -36,7 +36,7 @@ Features Installation ------------ -The package ``delft3dfmpy`` requires you to have (a) environment with required dependencies and (b) an Integrated Development Envrionment (IDE) that can access this envrionment. +The package ``delft3dfmpy`` requires you to have (a) an environment with required dependencies and (b) an Integrated Development Envrionment (IDE) that can access this envrionment. Please meet these two conditions first with instructions below before installing the Python package ``delft3dfmpy``. @@ -77,7 +77,7 @@ Prepare an environment with the correct dependencies for ``delft3dfmpy``. Envrionment Integration in your IDE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Integration of the prepared envrionment depends on the IDE of usage. Here we mention briefly some options for the user: +Integration of the prepared envrionment depends on the IDE of usage. Here we mention briefly some options for the user (pick one!): 1. For a new instance of Jupyter within the activated environment: