How to Сontribute

How to Сontribute#

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and you always earn credits.

You can contribute on the code side in many ways:

  • submit feedback,

  • add new features,

  • report bugs,

  • fix bugs,

  • implement a new cluster/cloud computation backend,

  • write documentation

Code#

Linting and pre-commit#

For every code contribution you should run pre-commit. This will lint, format and check your code contributions against our guidelines (e.g. we use Black as code style and aim for REUSE compliance):

  1. Installation conda install -c conda-forge pre-commit or pip install pre-commit

  2. Usage:

  • To automatically activate pre-commit on every git commit: Run pre-commit install

  • To manually run it: pre-commit run --all

Testing#

Add a new test if you want to contribute new functionality to the config. We currently perform multiple integration tests which means various workflows need to work. All test configs are build by updating config.tutorial.yaml with the configs in pypysa-earth/test/*.yaml.

  • You can test your contribution locally with make test.

  • See the Makefile for further information which configurations are tested.

To contribute a test:

  1. Provide a new test in test/<new test>.yaml, or adjust one of the existing ones. These tests update the config.tutorial.yaml to test other options e.g. landlock countries.

  2. Add a new test config path to the rule build_all_test in the Snakefile.

  3. If your functionality should be tested in the CI for every pull request, add a respective code in .github/workflows/ci-linux.yaml. We test all functionalities only for Linux while providing a general test for windows and mac.

Performance-profiling#

Performance profiling is important to understand bottlenecks and accordingly optimize the speed in PyPSA-Earth. We use the Python built-in cProfiler, custom decorators on single functions and analysis tools like snakeviz. See a detailed example in this discussion #557.

Documentation#

How to docs?#

We add the code documentation along the way. It might seem time-consuming and inefficient, but that’s not really true anymore! Documenting with great tools makes life much easier for YOU and YOUR COLLABORATORS and speeds up the overall process. Using Readthedocs and its add-on sphinx.ext.autodoc we document in our code scripts, which then will automatically generate the documentation you might see here.

Thank you Eric Holscher & team for your wonderful Readthedocs open source project. You can find an emotional speech by Eric here.

Structure and Syntax example#

The documentation is fully stored in our doc folder. You might note that most files are used as reStructuredText file or .rst which is very popular by coders when documentation matters.

You could differentiate between to elements:

  1. Non-automated doc elements. They simply make the text appealing. Example in installation.rst in our doc folder. To write these requires some knowledge on writing the text which is quite easy to learn having this **cheat sheet** in close reach.

  2. Automated doc elements using automoduleclass or similar. What they do is basically to link the code script with the doc texts, for instance, compare the python script add_electricity.py Example api_reference.rst with the documentation. To write these kind of automation, get inspiration from our or the pypsa doc for the api_reference documentation. Further, to help understanding how things work the official Sphinx documentation might help too.

We found three important files/file groups for the documentation:

  1. index.rst. This is the starter page of the Readthedocs page and also generates the sidebar with the outline (see pypsa).

  2. The .py script with the actual code documentation.

  3. conf.py with some useful information if something does not work.

The images for documentation should be placed into documentation repository to the folder “doc/img”. The content of the folder “documentation/doc/img/” is copied into “pypsa-earth/doc/img/” during building PyPSA-Earth documentation.

Please, if you have problems with the documentation create an issue and let us know

How to build it locally#

To create the documentation locally, you need Sphinx . It can be installed using specifications from doc/requirements.txt. First, we recommend creating a fresh conda environment and activate it:

.../pypsa-earth % conda create --name pypsa-earth-docs python

.../pypsa-earth % conda activate pypsa-earth-docs

Next, install the packages specified in doc/requirements.txt using pip:

.../pypsa-earth % pip install -r doc/requirements.txt

Once installation is completed, the following commands allow you to create the documentation locally:

.../pypsa-earth (pypsa-earth-docs) % cd doc

.../pypsa-earth/doc (pypsa-earth-docs) % make html

This will create html files in pypsa-earth/doc/_build/html. VScode provides a so called Liveserver extension such that the html file can be opened locally on your computer.

Warning

Windows users might face some challenges when building the documentation locally using make. A workaround can be found, but might be time consuming. For instance:

  1. If using Windows PowerShell, one might need to replace the command make html above by ./make html. For more details on what is going on, see this post on Stack Overflow.

Note

The documentation is built automatically by the CI for every pull request. The documentation is hosted on ReadTheDocs. For more information on our documentation infrastructure and syntax tips, see this page.

No-Code#

Instead of contributing code there are alternatives to support the PyPSA-Earth goals. You can fund projects, supervise people, support us with outreach activities or events. Check out our website for more details.

Join us and get involved#

Any person/ group is welcome to join us. Be it research leader, researcher, undergraduate, or industry professional. A simple way to explore opportunities for collaboration is to join our meetings. All of them are OPEN.

Contents