Contributions

If you have any new applications that require custom hooks or iterators feel free to contribute at any time.

EDflow is continuously expanded and gains new capabilities with every use. Examples of models are always welcome and we are happy if want to contribute in any way.

We are working on github and celebrate every pull request.

black

Before requesting a pull please run black for better code style or simply add black to your pre-commit hook:

0. Install black with

   $ pip install black
   

1. Paste the following into at the top <project-root>/.git/hooks/pre-commit.sample:

   # run black on all staged files
   staged=$(git diff --name-only --cached)
   black $staged
   # add them again after formatting
   git add $staged
   

2. Rename pre-commit.sample to pre-commit

3. Make it executable using:

   $ chmod +x pre-commit
   

4. Done!

Or run black by hand and use this command before every commit:

black ./

Continuous Integration

We use travisCI for continuous integration. You do not need to worry about it as long as your code passes all tests (this includes a formatting test with black).

Note

this should include an example to run the tests locally as well

Documenation

This is a short summary how the documentation works and how it can be built

The documentation uses sphinx and is available under readthedocs.org. It also uses all-contributors for honoring contributors.

sphinx

To build the documentation locally, install sphinx

pip install sphinx sphinx_rtd_theme sphinxcontrib-apidoc

and run

$ cd docs
$ make html

The html files are available under the then existing directory docs/_build/html/

The preferred docsting format is numpy.

We use sphinx-apidoc to track all files automatically::

$ cd docs
$ sphinx-apidoc -o ./source/source_files ../edflow

docs/conf.py contains a list of mocked dependencies. Make sure to add newly introduced dependencies to that list.

all-contributors

We use all-contributors locally and manage the contributors by hand.

To do so, install all-contributors as described here (we advise you to install it inside the repo but unstage the added files). Then run the following command to add a contributor or contribution::

all-contributors add <username> <contribution>

If this does not work for you (sometimes with npm the case) use::

./node_modules/.bin/all-contributors add <username> <contribution>

Known Issues

We noticed that mocking numpy in config.py will not work due to some requirements when importing numpy in EDFlow. Thus we need to require numpy when building the documentation.

Locally, this means that you need to have numpy installed in your environment.

Concerning readthedocs.org, this means that we require a readthedocs.yml in the source directory which points to extra_requirements in setup.py, where numpy is a dependency. Other dependencies are sphinx and sphinx_rtd_theme.