Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
99 lines (74 loc) · 4.35 KB

CONTRIBUTING.md

File metadata and controls

99 lines (74 loc) · 4.35 KB

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
  1. Install the package with the development dependencies and pre-commit hooks.

With uv:

uv sync --all-extras
pre-commit install

With pip:

pip install -e ./pkg/cuthbertlib
pip install -e "./pkg/cuthbert[tests,docs,examples]"
pre-commit install

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

  2. 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
!!! tip "VS Code Users"
    VS Code users can use the [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
    and [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
    (with Type Checking Mode: standard)
    extensions for assistance with linting and type checking during development.

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

  2. Open a pull request on GitHub.

Updating the docs

The documentation site is built with Zensical.

You can render locally with:

zensical serve

The live preview should be available at http://localhost:8000.

Pages under docs/ often pull shared copy from repository README.md files via PyMdown Snippets (--8<-- "path" and named sections in HTML comments). See that guide for syntax and options. We recommend using Snippets where possible, to avoid duplication, with source text in an appropriate README.md file and then linked to in docs/ files.

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.

  1. Add a reference to your new example in the docs/examples/index.md file and the zensical.toml file. You may need to add any new dependencies to the pyproject.toml file under examples.
  2. Make sure your example ends with "Key Takeaways" and "Next Steps" sections, linking to other documentation and examples where appropriate.
  3. 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