Write documentation and streamline general behaviour (#351)

* Add Mask subclass

* Add arithmetic tests and move __eq__ to raster_equal()

* Incremental commit on tests

* Finalize tests and linting

* Linting

* Make mypy happy

* Update nbands into count after merge of related PR

* Move doc to sphinx-book-theme

* Restructure

* Skeleton

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Quick start finalized!

* Incremental commit on docs

* Incremental commit on doc

* Pin dependencies for sphinx

* Incremental commit on doc

* Incremental commit on doc

* Remove jupyter myst folder

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on documentation

* Incremental commit on doc

* Incremental commit on doc

* Fix behaviour of load() with load_data=False as default, add and modify tests

* Add _repr_html_ functions

* Fix behaviour with load_data=False in _overloading_check and tests in satimg

* Update quick start with myst-nd and start new gallery of examples

* Incremental commit on gallery examples

* Merge and add new gallery folders to gitignore

* Incremental commit on example gallery

* Update sphinx env method

* Add mamba to readthedocs build

* Add self package install in dev-env

* Incremental commit on documentation

* Add logo to documentation

* Incremental commit on doc

* Incremental commit on doc

* Incremental commit on doc

* Add Vector.show and simplify gallery examples

* Fix sphinx errors

* Fix tests

* Fix tests

* Linting

* Make mypy ignore other files than core and tests

* Fix example

* Fix diff calculation with self install in dev env

* Now should work

* What about now?

* Hard reset cache

* Try to remove jinja condition now that mamba is solving

* Try pip --user option for Windows

* Array ufunc fixes

* Ensure array functions are cast to Raster if they preserve the shape (isfinite, isnan, isclose, etc)

* Linting

* Fix typo

* Linting

* Try to hard reset cache to fix Mac tests

* Update quick start

* Linting

* Force reset cache

* Update with sphinx-book-theme 1.0 release

* Linting

* Force cache reset again

* Fix path to doc

* Force cache reset again

* Add graphviz to dev environment for inheritance diagrams

* Add pygraphviz to dev environment as well...

* Fix incorrect parameter description in reproject

* Fix operator in value_to_coords

* Adapt tests to value_to_coords to check all values on pixel are resolved

* Fix cache re-loading error by moving all dependencies to conda-forge channel

* Fix parameter description

* Linting

* Clarify conf and modify title

* Add option as_array to Vector.create_mask() and index and index assignment to raster

* Add tests to pass a Mask to set_mask

* Make nodata values a tuple and not list to be immutable, and thus hashable

* Add test for shift

* Add tests for diff_env_yml

* Add test for diff_yml

* Linting

* Refactor crop_geom to remove camel-case, add geovector tests on missing coverage

* Fix cropGeom refactoring

* Streamline main description of functions in raster

* Streamline the function and attribute descriptions in geovector

* Linting

* Add test for to_xarray

* Linting

* Fix test_init

* Linting

* Add tests for diff_yml

* Add tests for mask overloaded functions and logical bitwise operations

* Linting

* Fix mask class methods

* Adjust repr test for mask

* Add more tests to spatial tools and georaster

* Add tests for geoviewer

* Linting

* Add tests in satimg

* Linting

* Homogenize errors and add tests for geoviewer

* Add random state tests for subsample

* Linting

* Add coveragerc file to exclude overload and importerrors that do not need to be tested

* Linting

* Fix tempfile error on Windows

* Add tests for coords(), that was malfunctioning

* Reorganize spatial tools into georaster/ modules

* Linting

* Rename modules georaster and geovector into raster and vector (geo is already in geoutils)

* Linting

* Homogenize syntax in docstrings

* Linting

* Reset cache for pip setup of new geoviewer

* Try to remove graphviz

* Incremental commit on wrapping GeoPandas API

* Finalize tests for GeoPandas interface

* Linting

* Fix misc description

* Update pre-commit

* Remove not implemented geopandas functions

* Wrap I/O geopandas method and fix tests

* Linting

* Define raster transform and crs as properties, remove the old attrs

* Linting

* Try to rename raster.py in raster to avoid errors on Mac and Windows

* Fix renaming with core

* Try to re-order init imports

* Change package setup to try fix on mac and windows

* Try re-installing via pip

* Fix raster into core in sphinx conf and doc

* Only run docs on Linux

* Linting

* Re-refactor into raster.py (not the source of error), and fix temporary files in test_save of raster and vector

* Linting

* Make sphinx gallery thumbnail not visible, remove open_save example files with post-build sphinx cleanup

* Linting

* Update logo

* Move forward on Vector documentation

* Linting

* Incremental commit on doc

* Linting

* Add tests for get_footprint_projected

* Add get_metric_crs and tests

* Add description of functions in projtools

* Linting

* Streamline README and CONTRIBUTING

* Linting

* Streamline README further

* Streamline README further

* Streamline agaaain

* Finish README

* Again

* Try this

* Make a bit better again

* And a bit more again

* Linting

* Cast .data of single-band rasters to 2D, fix methods and tests

* Linting and fix some inconsistencies

* Fix docs

* Add xarray and rioxarray to main environment

* Account for amaurys comments

* Linting

* Finish accounting for comments

* Linting

* Change default mode to dark to remove logo issue

* Add binder

* Add myst-nb to binder environment to open .md files as jupyter notebooks

* Replace by myst-nb for binder env

* Add default parameters for JupyterLab opening of markdown into Binder build

* Add display name

* Try with more jupytext settings

* Update documentation pages with binder setup

* Linting

* Modify repo url to main before merging

* Clarify settings of conf and postbuild

.coveragerc

@@ -0,0 +1,5 @@
+[report]
+exclude_lines =
+    pragma: not covered
+    @overload
+    except ImportError

.github/workflows/python-app.yml

@@ -48,7 +48,7 @@ jobs:
         path: ${{ env.CONDA }}/envs
         key: conda-${{ matrix.os }}-${{ matrix.python-version }}-${{ steps.get-date.outputs.month }}-${{ hashFiles('dev-environment.yml') }}-${{ env.CACHE_NUMBER }}
       env:
-        CACHE_NUMBER: 5 # Increase this value to reset cache if environment.yml has not changed
+        CACHE_NUMBER: 102 # Increase this value to reset cache if environment.yml has not changed
       id: cache
 
     # The trick below is necessary because the generic environment file does not specify a Python version, and only
@@ -79,7 +79,7 @@ jobs:
         pkgs_pip_dev=`python -c "import geoutils; geoutils.misc.diff_environment_yml('environment.yml', 'dev-environment.yml', 'pip')"`
         mamba install $pkgs_conda_dev --freeze-installed
         if [[ "$pkgs_pip_dev" != "None" ]]; then
-          pip install $pkgs_pip_dev
+          pip install --user $pkgs_pip_dev
         fi
 
     # Stop the build if there are Python syntax errors or undefined names

.gitignore

@@ -141,8 +141,17 @@ geoutils/version.py
 # End of https://www.gitignore.io/api/python
 .vim/
 doc/source/file.txt
-doc/source/auto_examples/
+doc/source/io_examples/
+doc/source/handling_examples/
+doc/source/analysis_examples/
 doc/source/gen_modules/
 
 # Directories where example data is downloaded
 examples/data/
+
+# Directory where myst_nb executes jupyter code
+doc/jupyter_execute/
+
+# Files that should have been deleted by Sphinx at end of build (but can exist if build fails)
+examples/io/open_save/myraster.tif
+examples/io/open_save/myvector.gpkg

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
                   types_or: [python, rst, markdown]
                   files: ^(geoutils|doc|tests)/
 
-        # Replace relative imports (e.g. 'from . import georaster' -> 'from geoutils import georaster')
+        # Replace relative imports (e.g. 'from . import raster' -> 'from geoutils import raster')
         - repo: https://github.com/MarcoGorelli/absolufy-imports
           rev: v0.3.1
           hooks:
@@ -44,7 +44,7 @@ repos:
                   files: ^(geoutils|tests)
         # Lint the code using mypy
         - repo: https://github.com/pre-commit/mirrors-mypy
-          rev: v0.982
+          rev: v1.1.1
           hooks:
                 - id: mypy
                   args: [
@@ -54,12 +54,12 @@ repos:
                         --show-error-codes,
                         --no-warn-unused-ignores,  # Ignore 'type: ignore' comments that are not used.
                         --disable-error-code=attr-defined,  # "Module has no attribute 'XXX'" occurs because of the pre-commit env.
-                        --disable-error-code=name-defined  # "Name 'XXX' is not defined" occurs because of the pre-commit env.
-
+                        --disable-error-code=name-defined,  # "Name 'XXX' is not defined" occurs because of the pre-commit env.
+                        --disable-error-code=var-annotated,
+                        --disable-error-code=no-any-return
                   ]
                   additional_dependencies: [tokenize-rt==3.2.0]
-
-
+                  files: ^(geoutils|tests)
 
         # Sort imports using isort
         - repo: https://github.com/PyCQA/isort

.readthedocs.yml → .readthedocs.yaml

@@ -5,6 +5,11 @@
 # Required
 version: 2
 
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "mambaforge-4.10"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: doc/source/conf.py
@@ -13,9 +18,6 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: []
 
-python:
-  version: 3.8
-  install:
-    - requirements: dev-requirements.txt
-    - method: pip
-      path: .
+
+conda:
+  environment: dev-environment.yml

CONTRIBUTING.md

@@ -1,103 +1,53 @@
 # How to contribute
 
 ## Overview: making a contribution
+
 For more details, see the rest of this document.
 
-1. Fork and clone the repository.
-2. Set up the development environment.
+1. Fork _GlacioHack/geoutils_ and clone your fork repository locally.
+2. Set up the development environment (section below).
 3. Create a branch for the new feature or bug fix.
-4. Make your changes, ensuring they are conventions-compliant.
+4. Make your changes, and add or modify related tests in _tests/_.
 5. Commit, making sure to run `pre-commit` separately if not installed as git hook.
-6. Push.
-7. Open a Pull Request to discuss and eventually merge.
-8. You can now delete your feature branch.
-
-
-## Rights
-The license (see LICENSE) applies to all contributions.
-
-
-## Issue Conventions
-When submitting bugs, please fill out the bug report template in full.
-
-Please search existing issues, open and closed, before creating a new one.
-
-
-## Git conventions
-Work on features should be made on a fork of `geoutils` and submitted as a pull request (PR) to master or a relevant branch.
-
-
-## Code conventions
-
-Contributors of `geoutils` should attempt to conform to pep8 coding standards.
-An exception to the standard is having a 120 max character line length (instead of 80).
-
-Suggested linters are:
-1. prospector
-2. mypy (git version)
-3. pydocstyle
-
-Suggested formatters are:
-1. autopep8
-2. isort
-
-## Test conventions
-At least one test per feature (in the associated `tests/test_*.py` file) should be included in the PR, but more than one is suggested.
-We use `pytest`.
-
+6. Push to your fork.
+7. Open a pull request from GitHub to discuss and eventually merge.
 
 ## Development environment
-We target Python 3 or higher for `geoutils`.
-Some features may require later versions of Python (3.6+) to function correctly.
 
+GeoUtils currently supports only Python versions of 3.8 and higher, see `environment.yml` for detailed dependencies.
 
 ### Setup
 
-Clone the git repo and create a conda environment:
+Clone the git repo and create a `mamba` environment (see how to install `mamba` in the [mamba documentation](https://mamba.readthedocs.io/en/latest/)):
 
 ```bash
 git clone https://github.com/GlacioHack/geoutils.git
 cd geoutils
-conda env create -f environment.yml  # add '-n custom_name' if you want.
-conda activate geoutils  # or any other name specified above
-pip install -e .  # Install geoutils in developer mode
+mamba env create -f dev-environment.yml  # Add '-n custom_name' if you want.
+mamba activate geoutils-dev  # Or any other name specified above
 ```
 
-Now install the additional development dependencies:
-```bash
-pip install -r dev-requirements.txt
-```
-
-Finally, we also recommend installing the formatting and linting tools listed above to help with adhering to code conventions:
-```bash
-pip install prospector git+https://github.com/python/mypy.git pydocstyle autopep8 isort
-```
-
-Note that your text editor of choice will also need to be configured with these tools (and max character line length changed to 120).
+### Tests
 
+At least one test per feature (in the associated `tests/test_*.py` file) should be included in the PR, using `pytest` (see existing tests for examples).
 
-### Running the tests
 To run the entire test suite, run `pytest` in the current directory:
 ```bash
 pytest
 ```
 
-It is also recommended to try the tests from the parent directory, to validate that import statements work as they should:
-```bash
-cd ../  # Change to the parent directory
-pytest geoutils
-```
-
 ### Formatting and linting
-To merge a PR in geoutils, the code has to adhere to the standards set in place.
-We use a number of tools to validate contributions, triggered using `pre-commit` (see `.pre-commit-config.yaml` for the exact tools).
 
-`pre-commit` is made to be installed as a "pre-commit hook" for git, so the checks have to pass before committing. Before committing for the first time, you need to install the hook:
-```bash
-pre-commit install
-```
+Install and run `pre-commit` (see [pre-commit documentation](https://pre-commit.com/)), which will use `.pre-commit-config.yaml` to verify spelling errors,
+import sorting, type checking, formatting and linting.
 
-Pre-commit can also be run as a separate tool:
+You can then run pre-commit manually:
 ```bash
 pre-commit run --all-files
 ```
+
+Optionally, `pre-commit` can be installed as a git hook to ensure checks have to pass before committing.
+
+## Rights
+
+The license (see LICENSE) applies to all contributions.

README.md

@@ -1,5 +1,4 @@
-# geoutils
-Set of tools to handle raster and vector data sets in Python.
+# GeoUtils: consistent geospatial analysis in Python.
 
 ![](https://readthedocs.org/projects/geoutils/badge/?version=latest)
 [![build](https://github.com/GlacioHack/geoutils/actions/workflows/python-app.yml/badge.svg)](https://github.com/GlacioHack/GeoUtils/actions/workflows/python-app.yml)
@@ -9,51 +8,43 @@ Set of tools to handle raster and vector data sets in Python.
 [![PyPI version](https://badge.fury.io/py/geoutils.svg)](https://badge.fury.io/py/geoutils)
 [![Coverage Status](https://coveralls.io/repos/github/GlacioHack/geoutils/badge.svg?branch=main)](https://coveralls.io/github/GlacioHack/geoutils?branch=main)
 
-This package offers Python classes and functions as well as command line tools to work with both geospatial raster and vector datasets. It is built upon rasterio and GeoPandas. In a single command it can import any geo-referenced dataset that is understood by these libraries, complete with all geo-referencing information, various helper functions and interface between vector/raster data.
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/GlacioHack/geoutils/main)
+[![Pre-Commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Formatted with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
 
+**GeoUtils** is an open source project to develop a core Python package for geospatial analysis and foster inter-operability between other Python GIS packages.
 
-## Installation
-
-#### With conda (recommended)
-```bash
-conda install --channel conda-forge --strict-channel-priority geoutils
-```
-The `--strict-channel-priority` flag seems essential for Windows installs to function correctly, and is recommended for UNIX-based systems as well.
+It aims at **facilitating end-user geospatial analysis by revolving around consistent `Raster` and `Vector` objects** that effortlessly interface between
+themselves. GeoUtils is founded on **implicit loading behaviour**, **robust numerical interfacing** and **convenient object-based methods** to easily perform
+the most common higher-level tasks needed by geospatial users.
 
-#### With pip
-
-From PyPI:
-```bash
-pip install geoutils
-```
+If you are looking for an accessible Python package to write the Python equivalent of your [GDAL](https://gdal.org/) command lines, or of your
+[QGIS](https://www.qgis.org/en/site/) analysis pipeline **without a steep learning curve** on Python GIS syntax, GeoUtils is perfect for you! For more advanced
+users, GeoUtils also aims at being efficient and scalable by supporting lazy loading and parallel computing (ongoing).
 
-Or from the repository tarball: make sure GDAL and PROJ are properly installed, then:
-```bash
-pip install https://github.com/GlacioHack/geoutils/tarball/main
-```
+GeoUtils relies on [Rasterio](https://github.com/rasterio/rasterio), [GeoPandas](https://github.com/geopandas/geopandas) and [Pyproj](https://github.com/pyproj4/pyproj) for georeferenced
+calculations, and on [NumPy](https://github.com/numpy/numpy) and [Xarray](https://github.com/pydata/xarray) for numerical analysis. It allows easy access to
+the functionalities of these packages through interfacing or composition, and quick inter-operability through object conversion.
 
 ## Documentation
-See the full documentation at https://geoutils.readthedocs.io.
-
-
-## Structure
 
-GeoUtils is composed of three libraries:
-- `georaster.py` to handle raster data set. In particular, a Raster class to load a raster file along with metadata.
-- `geovector.py` to handle vector data set. In particular, a Vector class to load a raster file along with metadata.
-- `projtools.py` with various tools around projections.
+For installation, quick start, gallery examples, a full feature description or a search through the API, see GeoUtils' documentation at:
+https://geoutils.readthedocs.io.
 
+## Installation
 
-## How to contribute
+```bash
+mamba install -c conda-forge geoutils
+```
 
-You can find ways to improve the libraries in the [issues](https://github.com/GlacioHack/geoutils/issues) section. All contributions are welcome.
+See [mamba's documentation](https://mamba.readthedocs.io/en/latest/) to install `mamba`, which will solve your environment much faster than `conda`.
 
-1. Fork the repository to your personal GitHub account, clone to your computer.
-2. (Optional but preferred:) Make a feature branch.
-3. Push to your feature branch.
-4. When ready, submit a Pull Request from your feature branch to `GlacioHack/geoutils:master`.
-5. The PR will be reviewed by at least one other person. Usually your PR will be merged via 'squash and merge'.
+## Start contributing
 
-Direct pushing to the GlacioHack repository is not permitted.
+1. Fork the repository, make a feature branch and push changes.
+2. When ready, submit a pull request from the feature branch of your fork to `GlacioHack/geoutils:main`.
+3. The PR will be reviewed by at least one maintainer, discussed, then merged.
 
-A more detailed contribution instruction [can be found here](CONTRIBUTING.md).
+More info on [our contributing page](CONTRIBUTING.md).