π Contribution Guideο
π· Get in touchο
Hey! Nice to see that youβre interested in contributing to EOmaps!
If you need help to get started or got some questions, open a new Issue on GitHub, start a Discussion on GitHub or post a message on gitter and Iβll see what I can do!
Any contributions are welcome!
New feature implementations (or ideas for new features)
Enhancements for existing features
Bug-fixes, code-style improvements, unittests etc.
Documentation updates
Outreach (e.g. blog-posts, tutorials, talks β¦ )
β¦
πGetting startedο
The source code of EOmaps is managed on GitHub.
To get started, create a new fork of the EOmaps repository to get your own copy of the source code.
Then, open a terminal, navigate to the folder you want to work in and clone the forked repository via:
git clone < link to your fork of the EOmaps repository >
For development, make sure that you first checkout the dev
branch which contains all pending changes for the next release.
Then, create a new feature or bug-fix branch and start coding!
git checkout dev
git checkout -b "awesome_new_feature"
Once youβre done or in case you want/need some feedback, open a pull request on GitHub!
β How to set up a development environmentο
To contribute to EOmaps
, you need a working python
installation.
I recommend using miniconda to set up python
with the following steps:
Download the latest miniconda installer and install
Open anaconda prompt (or normal terminal on
linux
)- Install mamba with
conda install -c conda-forge mamba
- Create a development environment from the
eomaps.yml
file withmamba env create -f < path to eomaps.yml >
Content of eomaps.yml
:
name: eomaps
channels:
- conda-forge
dependencies:
- python = 3.10
- numpy
- scipy
- pandas
- geopandas
- matplotlib >=3.4
- cartopy >=0.20.0
- descartes
- mapclassify
- pyproj
- pyepsg
# --------------for data-shading
- datashader
# --------------for GeoTIFF and NetCDF files
- netcdf4
- xarray
- rioxarray
# --------------for WebMaps
- owslib
- requests
- xmltodict
- cairosvg
# --------------for testing
- coveralls
- pytest
- pytest-cov
# --------------for version control
- git
- pre-commit
# --------------for building the docs
- sphinx-copybutton
- sphinx
- docutils
- pip
- pip:
- sphinx_rtd_theme
As editor, I recommend using the awesome, free and open-source Spyder IDE. You can install it directly into your environment via:
mamba install -c conda-forge spyder
Pre-commit hooksο
To ensure uniform code formatting, EOmaps uses pre-commit hooks to automatically check (and fix) code-style issues such as:
Trailing spaces in .py files
Compliance to the used black code formatting standards
To initialize pre-commit hooks in your current environment, navigate to the directory where you cloned the EOmaps repository and run the following command:
(e.g. the parent directory containing the file .pre-commit-config.yaml
)
pre-commit install
This will install the required pre-commit hooks in your current environment so that they are run automatically prior to each commit. (The first time pre-commit is run, the necessary packages will have to be installed which might take a short moment)
Note
This means that all files will be auto-formatted prior to each commit to comply with the used code-formatting standards and only commits that comply with all pre-commit hooks can be pushed to GitHub.
To run the pre-commit hooks manually on selected files, simply add the files you want to commit with
git add < filename >
and then runpre-commit
If you want to run the hooks on all files, use
pre-commit run --all-files
Note: after running the pre-commit hooks, some files might have new changes that must be staged for commit again!
π Building the docsο
The documentation of EOmaps is written with Sphinx using the markup language ReStructuredText.
To build the documentation locally, simply navigate to the folder eomaps/docs
and then run
make html
The first time the documentation is built, all auto-generated files parsed from the python-code have to be generated which might take a bit of time. Subsequent calls will be much faster since they only update files that contain changes!
Once finished, you will find a new folder in the EOmaps directory (
eomaps/docs/build/html
) that contains all the source files for the documentation.Open
eomaps/docs/build/html/index.html
to get to the starting-page!
Automating the build process
Manually re-building the documentation can be tedious⦠fortunately it is possible to automatically re-build the documentation if a file changed and live-reload the local docs in the browser with the awesome sphinx-autobuild package.
To install, run mamba install -c conda-forge sphinx-autobuild
.
After installation, navigate to the eomaps
directory and start the automatic build-process with
sphinx-autobuild docs docs/build/html --ignore ["generated/*"] --open-browser
This will trigger a first build of the documentation and start a http server that hosts the local documentation (and live reloads it as soon as the build process finished)
As editor for the docs I recommend the nice free and open-source editor retext. It provides syntax-highlighting for ReStructuredText and a useful table-edit mode.