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 get the source code from GitHub run:

git clone https://github.com/rodrigopcastro018/nodimo

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.