Contributing¶

This section provides some instructions for those who want to contribute with the development of Nodimo.

Development Environment¶

Git and GitHub¶

Nodimo is available on GitHub and uses Git for source control. To contribute to the project with these tools, follow the GitHub instructions.

Virtual Environment¶

Isolate you development environment by using virtual environments. In the repository folder, execute:

python -m venv .venv

Activate the virtual environment by running:

.venv/scripts/activate

From the repository folder, install Nodimo in editable mode with:

pip install -e .

Tests¶

Currently, Nodimo tests are integrated with GitHub Actions. The tests coverage are published by smokeshow.

Tests status:

Tests coverage:

To manually execute Nodimo tests, follow the instructions in the next subsection.

Manual testing¶

To install Nodimo testing dependencies, run:

pip install -e .[test]

Nodimo contains type hints that can be checked with mypy by running:

mypy

Main functionalities can be tested with pytest by executing:

pytest

The nbval plugin is responsible for testing the ipynb files, while the pytest-cov plugin includes these files in the reports generated by coverage.

Note

Configurations for mypy and pytest can be found in the pyproject.toml file.

Testing multiple environments¶

Nodimo can be tested for multiple versions of its dependencies and python. Multiple python versions can be installed with pyenv (or pyenv-win for windows). The package tox can be used for test automation.

Note

During the development of Nodimo on Windows, it was also necessary the installation of tox-pyenv-redux to enable the discovery of the pyenv python environments by tox.

Note

The tox configuration found in the pyproject.toml file is set to be used by the corresponding integrated github workflow.

Documentation¶

Currently, the documentation is being automatically built and hosted by Read the Docs.

Documentation status:

To manually build the documentation, read the instructions in the following subsection.

Build documentation¶

The documentation is built with Sphinx, using Furo as a theme. Tutorials made with jupyter notebook were added to the documentation using the extension nbsphinx, copy buttons for code blocks are supported by sphinx-copybutton, and docstrings follow the numpydoc standard.

To work properly, nbsphinx requires the installation of IPython and pandoc. It’s recommended to install the latter manually.

To install all these dependencies (except pandoc), just execute:

pip install -e .[docs]

From the docs folder, create the html files by running:

on Windows:
```
./make.bat html
```
on Linux or macOS:
```
make html
```

Formatting¶

Code formatting follows the style established by black.

Publishing and Maintenance¶

Nodimo is published in PyPI and Anaconda repositories. Bellow are given some pages with instructions that were followed in the publishing process and are left as reference.