Contributing
Documentation
The documentation consists of two parts: the docstrings in the code itself and the docs in this folder
nml_meld/docs/
.The documentation is written in reStructuredText and built using Sphinx.
The docstrings follow the Numpy Docstring Standard.
How to build the documentation:
# Create and activate the docs environment
conda env create -f nml_meld/ci/docs.yml
conda activate nmlmeld_docs
# Navigate to the docs directory
cd nml_meld/docs/
# If you want to do a full clean build
make clean
# Build the documentation
make html
Tests
All tests go into this folder
nml_meld/nmlmeld/tests
.We are using pytest for testing.
Test functions should look like this:
def add_one(x):
return x + 1
def test_add_one():
expected = 2
actual = add_one(1)
assert expected == actual
How to run the tests:
# Create and activate the test environment
conda env create -f nml_meld/ci/environment.yml
conda activate nmlmeld_test
# Navigate to the root directory and run pytest
cd nml_meld
pytest
Pre-commit formatting
We are using several tools to ensure that code and docs are well formatted:
isort for standardized order in imports.
Black for standardized code formatting.
blackdoc for standardized code formatting in documentation.
Flake8 for general code quality.
Darglint for docstring quality.
mypy for static type checking on type hints.
doc8 for reStructuredText documentation quality.
Setup pre-commit hooks to automatically run all the above tools every time you make a git commit:
# Install the pre-commit package manager.
conda install -c conda-forge pre-commit
# Set up the git hook scripts.
cd nml_meld
pre-commit install
# Now pre-commit will run automatically on the changed files on ``git commit``
# Alternatively, you can manually run all the hooks with:
pre-commit run --all
# You can skip the pre-commit checks with:
git commit --no-verify