Contributing

We love to chat about state-space-models! If you do too, you can get involved in the following ways:

• Open an issue if you have a question, suggestion or spotted a bug or specific code that could be improved.
• Start or join a discussion for more general conversation regarding cuthbert code structure and design.
• Open a pull request to add code yourself, follow the steps below (feel free to make it a draft at an early stage for feedback).
• Join us on discord for everything else; including memes, research ideas and meetups.

Opening a Pull Request

If you would like to contribute to cuthbert, please follow these steps:

1. Fork the repo from GitHub and clone it locally:

   git clone git@github.com/YourUserName/cuthbert.git
   cd cuthbert
   

2. Install the package with the development dependencies and pre-commit hooks:

   pip install -e ".[tests, docs]"
   pre-commit install
   

3. Add your code. Add your tests. Update the docs if needed.

4. If you have made changes to the docs, check that they render nicely:

   mkdocs serve
   

5. Make sure to run the linter, type checker, tests and check coverage:

   pre-commit run --all-files
   python -m pytest --cov=cuthbert --cov-report term-missing
   

   VS Code Users

   VS Code users can use the Ruff and Pylance (with Type Checking Mode: standard) extensions for assistance with linting and type checking during development.

6. Commit your changes and push your new branch to your fork.

7. Open a pull request on GitHub.

Adding an example

Examples in cuthbert are written in Markdown and tangled into Python scripts using entangled so they can be run as tests.

To add an example, you can use the following steps:

1. Write the example in Markdown in the docs directory.
2. Make sure to start each code block with {.python #example_name-code_block_name}. See the docs/quickstart.md example for reference.
   (Note that it's important to include the example name here as code block names must be unique across all examples.)

3. Add a hidden code block at the end of the file with the following content:

   ```{.python file=examples_scripts/example_name.py}
   <<example_name-code_block_name_1>>
   <<example_name-code_block_name_2>>
   ...
   

   Again, see the docs/quickstart.md example for reference.

4. Add a reference to your new example in the docs/examples/index.md file and the mkdocs.yml file.
   You may need to add any new dependencies to the pyproject.toml file under examples.

5. Make sure your example ends with "Key Takeaways" and "Next Steps" sections, linking to other documentation and examples where appropriate.
6. That's it! If you want to generate the python script and run it locally to check it works, you can run:

   entangled tangle
   python examples_scripts/example_name.py