Merge pull request #7 from mattijn/improve-contributing

Improve text readme for contributing

README.rst

@@ -36,16 +36,28 @@ Features
 Installation
 ------------
 
-By the following procedure you can install the delft3dfmpy module:
+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``.
+
+
+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,33 +74,61 @@ 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 (pick one!): 
+
+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
 -----
 
-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
 
 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 for development purposes do the following:
+
+        From an elevated Anaconda Prompt (run as Administrator) within the activated ``delft3dfmpy`` environment:
+
+        ``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. 

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"
-]
+]