Merge eab7c3b into 224a9ea

.gitignore

@@ -69,11 +69,11 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
-docs/build/
-docs/source/api/
-docs/.buildinfo
-docs/.doctrees
+doc/_build/
+doc/build/
+doc/source/api/
+doc/.buildinfo
+doc/.doctrees
 
 # PyBuilder
 target/
@@ -145,7 +145,10 @@ examples/data/Longyearbyen/processed/
 examples/data/*.tif
 examples/data/*.csv
 
-docs/source/basic_examples/
-docs/source/advanced_examples/
-docs/source/gen_modules/
+doc/source/basic_examples/
+doc/source/advanced_examples/
+doc/source/gen_modules/
 examples/basic/temp.tif
+
+# Directory where myst_nb executes jupyter code
+doc/jupyter_execute/

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
                     '--'
                   ]
                   types_or: [python, rst, markdown]
-                  files: ^(xdem|docs|tests)/
+                  files: ^(xdem|doc|tests)/
 
         # Replace relative imports (e.g. 'from . import georaster' -> 'from geoutils import georaster')
         - repo: https://github.com/MarcoGorelli/absolufy-imports
@@ -70,7 +70,7 @@ repos:
 
                   ]
                   additional_dependencies: [tokenize-rt==3.2.0, numpy==1.22]
-                  files: ^(xdem|tests|docs/code)
+                  files: ^(xdem|tests|doc/code)
 
 
         # Sort imports using isort

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "mambaforge-4.10"
+
+# Build documentation in the doc/ directory with Sphinx
+sphinx:
+  configuration: doc/source/conf.py
+  fail_on_warning: false
+
+# Optionally build your doc in additional formats such as PDF and ePub
+formats: []
+
+conda:
+  environment: dev-environment.yml

CONTRIBUTING.md

@@ -1,104 +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/xdem_ 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 MIT license (see LICENSE) applies to all contributions.
-
-## Issue Conventions
-When submitting bugs, please include the following information:
-* Operating system type and version (Windows 10 / Ubuntu 18.04 etc.).
-* The version and source of `xdem` (PyPi, Anaconda, GitHub or elsewhere?).
-* The version and source of `geoutils`, `rasterio` and `GDAL`.
-
-Please search existing issues, open and closed, before creating a new one.
-
-## Git conventions
-Work on features should be made on a fork of `xdem` and submitted as a pull request (PR) to main or a relevant branch.
-
-## Code conventions
-
-Contributors of `xdem` 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
-
-These can all be installed with this command:
-```bash
-pip install prospector git+https://github.com/mypy/mypy.git pydocstyle autopep8 isort
-```
-Note that your text editor of choice will also need to be configured with these tools (and max character length changed).
-
-## 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 `xdem`.
-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/xdem.git
 cd xdem
-conda create -f environment.yml  # add '-n custom_name' if you want.
-conda activate xdem  # or any other name specified above
-pip install -e .  # Install xdem
-```
-The linters and formatters mentioned above are recommended to install now.
-
-### Running the tests
-To run the entire test suite, run pytest in the current directory:
-```bash
-pytest
+mamba env create -f dev-environment.yml  # Add '-n custom_name' if you want.
+mamba activate xdem-dev  # Or any other name specified above
 ```
 
-A single test file:
-```bash
-pytest tests/test_volume.py
-```
+### Tests
 
-Or a single test:
-```bash
-pytest tests/test_volume.py::TestLocalHypsometric
-```
+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).
 
-It is also recommended to try the tests from the parent directory, to validate that import statements work as they should:
+To run the entire test suite, run `pytest` in the current directory:
 ```bash
-cd ../  # Change to the parent directory
-pytest xdem
+pytest
 ```
 
 ### Formatting and linting
-To merge a PR in xdem, 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.