diff --git a/README.md b/README.md deleted file mode 100644 index 67d66c4..0000000 --- a/README.md +++ /dev/null @@ -1,83 +0,0 @@ -Documentation: https://deltares.gitlab.io/imod/qgis-tim - -This repository contains two Python packages: - -* `./plugin` contains the source code for a QGIS plugin. This plugin provides a - limited graphical interface to setup a - [GeoPackage](https://www.geopackage.org/) containing the vector data required - by a [TimML](https://github.com/mbakker7/timml) analytic element model and - read results. -* `./gistim` contains the functions required to transform a GeoPackage into a - TimML model. It is fully independent of the plugin, relying on packages such - as `rasterio` and `geopandas` instead of QGIS functions. The utilities it - provides can be used independently of QGIS, in a fully scripted workflow. - -# Installation requirements - -In terms of development requirements, the packages are independent as well. The -plugin requires: - -* A modern (>=3.0) QGIS installation, within the context of - [OSGeo4W](https://trac.osgeo.org/osgeo4w/). A basic QGIS installation (as can - be gotten [here](https://qgis.org/en/site/)) suffices to run the plugin, but - will not suffice for full development capabilities. - -The QGIS installation comes with its own Python installation and interpreter. -This installation does not provide a package manager such as -[conda](https://docs.conda.io/en/latest/). This complicates the distribution of -complex binary dependencies. Hence, the `gistim` package (and TimML) should run -in a different interpreter. This requires: - -* A modern Python version (>=3.6) -* [GeoPandas](https://geopandas.org/) -* [Xarray](https://xarray.pydata.org/en/stable/), which in turn requires numpy - and pandas -* [Rasterio](https://rasterio.readthedocs.io/en/latest/) -* [rioxarray](https://corteva.github.io/rioxarray/stable/index.html) -* [netCDF4](https://unidata.github.io/netcdf4-python/netCDF4/index.html) - -Rasterio, rioxarray, and netCDF4 are optional dependencies but output options -are severely limited without them. Both geopandas and rasterio requires GDAL, -which is a heavy and complex binary dependency. It is highly recommended to -install these packages via `conda` in a separate environment -- the -specification is included in the `environment.yml` of this repository. - -See the installation instruction below. - -# Installing the plugin in QGIS - -There are a few ways to install this plugin: - -* Copy the directory `./plugin/qgistim` to your local QGIS plugins directory. - On Windows, this should be located at: - - `c:\Users\{username}\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins` - - The location can be found in the QGIS GUI via: - - QGIS menu > Settings > User Profiles > Open Active Profile Folder - -* Alternatively, zip the `./plugin/qgistim` directory. Then, in the Plugins - menu, under "Manage and Install Plugins...", find "Install from ZIP", and - enter the path to the zipfile -- this unzips the files and copies them to the - directory mentioned above. - -The plugin is good to go now. Find the Qgis-Tim entry in the Plugins menu, and -click it to open a docked menu on the right side of your QGIS screen. - -# Installing the Python package - -The recommended way of installing is using conda, in a separate conda -environment. This environment (called `tim`) can be setup by downloading the -`environment.yml` and running the following command in the anaconda prompt: - -``` -conda env create -f environment.yml -``` - -After creation, the conda environment can be activated by running the following -command in the anaconda prompt: - -``` -conda activate tim -``` diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..6b859d4 --- /dev/null +++ b/README.rst @@ -0,0 +1,89 @@ +QGIS-Tim +======== + +Documentation: https://deltares.gitlab.io/imod/qgis-tim + +This repository contains two Python packages: + +* ``./plugin`` contains the source code for a QGIS plugin. This plugin provides a + limited graphical interface to setup a + `GeoPackage `_ containing the vector data required + by a `TimML `_ analytic element model and + read results. +* ``./gistim`` contains the functions required to transform a GeoPackage into a + TimML model. It is fully independent of the plugin, relying on packages such + as ``rasterio`` and ``geopandas`` instead of QGIS functions. The utilities it + provides can be used independently of QGIS, in a fully scripted workflow. + +Installation requirements +------------------------- + +In terms of development requirements, the packages are independent as well. The +plugin requires: + +* A modern (>=3.0) QGIS installation, within the context of + `OSGeo4W `_. A basic QGIS installation (as can + be gotten `here `_ suffices to run the plugin, but + will not suffice for full development capabilities. + +The QGIS installation comes with its own Python installation and interpreter. +This installation does not provide a package manager such as +`conda `_. This complicates the distribution of +complex binary dependencies. Hence, the ``gistim`` package (and TimML) should run +in a different interpreter. This requires: + +* A modern Python version (>=3.6) +* `GeoPandas `_ +* `Xarray `_, which in turn requires numpy + and pandas +* `Rasterio `_ +* `rioxarray `_ +* `netCDF4 `_ + +Rasterio, rioxarray, and netCDF4 are optional dependencies but output options +are severely limited without them. Both geopandas and rasterio requires GDAL, +which is a heavy and complex binary dependency. It is highly recommended to +install these packages via ``conda`` in a separate environment -- the +specification is included in the ``environment.yml`` of this repository. + +See the installation instruction below. + +Installing the plugin in QGIS +----------------------------- + +There are a few ways to install this plugin: + +* Copy the directory ``./plugin/qgistim`` to your local QGIS plugins directory. + On Windows, this should be located at: + + ``c:\Users\{username}\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins`` + + The location can be found in the QGIS GUI via: + + QGIS menu > Settings > User Profiles > Open Active Profile Folder + +* Alternatively, zip the ``./plugin/qgistim`` directory. Then, in the Plugins + menu, under "Manage and Install Plugins...", find "Install from ZIP", and + enter the path to the zipfile -- this unzips the files and copies them to the + directory mentioned above. + +The plugin is good to go now. Find the Qgis-Tim entry in the Plugins menu, and +click it to open a docked menu on the right side of your QGIS screen. + +Installing the Python package +------------------------------- + +The recommended way of installing is using conda, in a separate conda +environment. This environment (called ``tim``) can be setup by downloading the +``environment.yml`` and running the following command in the anaconda prompt: + +.. code-block:: console + + conda env create -f environment.yml + +After creation, the conda environment can be activated by running the following +command in the anaconda prompt: + +.. code-block:: console + + conda activate tim diff --git a/setup.py b/setup.py index 0768d02..91ab20b 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ from setuptools import find_packages, setup -with open("README.md") as f: +with open("README.rst") as f: long_description = f.read() # Write all the environmental variables so the QGIS interpreter