🚀 Contribution Guide
👷 Get in touch
Hey! Nice to see that you’re interested in contributing to EOmaps!
Any contributions are welcome!
New feature implementations (or ideas for new features)
Enhancements for existing features
Bug-fixes, code-style improvements, unittests etc.
Outreach (e.g. blog-posts, tutorials, talks … )
The source code of EOmaps is managed on GitHub.
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
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
- Install mamba with
conda install -c conda-forge mamba
- Create a development environment from the
mamba env create -f < path to 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
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
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)
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 run
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
To build the documentation locally, simply navigate to the folder
eomaps/docs and then run
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.
eomaps/docs/build/html/index.htmlto 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.