Contributing

Community contributions are welcomed! 🎊

Installation for developers

• It is recommended that you create a virtual environment, e.g. using conda, venv, or similar.
• If you want to build the documentation locally you will also need to install pandoc and gifsicle. On Windows, we recommend installing pandoc using conda (i.e. conda install -c conda-forge pandoc)
• Building using pip on MacOS requires the manual installation of Fortran compilers, see discussion here. For ARM-based Macs, see issue #324
• On a ZSH shell (MacOS) do pip install -e .\[dev] instead of pip install -e .[dev] in the instructions below (i.e., escape the opening square bracket).

Using conda this looks like:

conda create -n wecopttool
conda activate wecopttool
conda install -c conda-forge python=3.12 capytaine wavespectra
git clone git@github.com:<YOUR_USER_NAME>/WecOptTool.git
cd WecOptTool
pip install -e .[dev]

And using pip:

git clone git@github.com:<YOUR_USER_NAME>/WecOptTool.git
cd WecOptTool
python3.12 -m venv .venv
. .venv/bin/activate
pip install -e .[dev]

Style guide

• Style guide: pep8.
• Docstrings: pep257 & NumPy style.
• Type hints: module documentation, cheat sheet.

Autograd

This project uses autograd for automatic differentiation. Autograd does not support all NumPy and SciPy functionalities, see autograd documentation. NOTE: using unsupported functionalities results in the gradient calculation failing silently.

Pull Requests

1. Create a fork of WecOptTool
2. Create a branch for the specific issue
3. Add desired code modifications. For enhancements add to documentation. Add or modify a test. Make sure all tests pass and documentation builds. Follow style guide above.
4. Do a pull request to the dev branch, and give admins edit access. Link to any open issues and add relevant tags. Use a concise but descriptive PR title, as this will be part of the release notes for the next version. Start the PR title with an all caps label followed by a colon, e.g., "BUG FIX: ...", "NEW FEATURE: ...", "DOCUMENTATION: ...", etc. Note: Pull requests should be made to the dev branch, not the main branch.

Tests

There are a series of unit and integration tests defined in the tests directory. These can be run by calling pytest from the root directory of the repository.

pytest

Continuous integration (CI)

This project uses GitHub Actions to run tests on pull requests.

Documentation:

See Documentation.

Editing the documentation

The documentation is built using Sphinx, and the Napoleon extension for automatic code documentation. The source code (restructured text) is in ./docs/source and images are in ./docs/source/_static. The homepage source code is in ./docs/source/index.rst.

To build the documentation locally (not required but good check), go to ./docs/versions.yaml and change the value of latest to be your local branch. Then run:

python3 docs/build_docs.py

The built documentation will be in ./docs/pages and the homepage is ./docs/pages/index.html. To delete, do python3 docs/clean_docs.py.

The documentation uses the Jupyter notebook tutorials in the examples directory. When building the documentation locally you will need to have installed pandoc and gifsicle. We recommend installing pandoc using its Anaconda distribution: conda install -c conda-forge pandoc.

NOTE: it may be expedient at times to avoid running the tutorial notebooks. To do so, add nbsphinx_execute = 'never' to docs/source/conf.py. Make sure not to commit these changes!

If you add or change any hyperlinks in the documentation, we recommend checking the "Build documentation" warnings in the GitHub Actions CI workflow to make sure the links will not cause an issue. The CI will not fail due to broken links, only issue a warning (see issue #286).

Editing the tutorials

The tutorials are used as part of the Documentation. Before pushing any changes make sure that the saved version of the notebooks are clear (no cells run and no results). To achieve this click clear outputs and save in that order. Alternatively create a pre-commit hook that strips the results.

Issue tracking

To report bugs use WecOptTool's issues page. For general discussion use WecOptTool's discussion page

Releasing (developers only)

See releasing instructions.