|
| 1 | +# rtichoke Agent Information |
| 2 | + |
| 3 | +This document provides guidance for AI agents working on the `rtichoke` repository. |
| 4 | + |
| 5 | +## Development Environment |
| 6 | + |
| 7 | +To set up the development environment, follow these steps: |
| 8 | + |
| 9 | +1. **Install `uv`**: If you don't have `uv` installed, please follow the official installation instructions. |
| 10 | +2. **Create a virtual environment**: Use `uv venv` to create a virtual environment. |
| 11 | +3. **Install dependencies**: Install the project dependencies, including the `dev` dependencies, with the following command: |
| 12 | + |
| 13 | + ```bash |
| 14 | + uv pip install -e .[dev] |
| 15 | + ``` |
| 16 | + |
| 17 | +## Running Tests |
| 18 | + |
| 19 | +The test suite is run using `pytest`. To run the tests, use the following command: |
| 20 | + |
| 21 | +```bash |
| 22 | +uv run pytest |
| 23 | +``` |
| 24 | + |
| 25 | +## Coding Conventions |
| 26 | + |
| 27 | +### Functional Programming |
| 28 | + |
| 29 | +Strive to use a functional programming style as much as possible. Avoid side effects and mutable state where practical. |
| 30 | + |
| 31 | +### Docstrings |
| 32 | + |
| 33 | +All exported functions must have NumPy-style docstrings. This is to ensure that the documentation is clear, consistent, and can be easily parsed by tools like `quartodoc`. |
| 34 | + |
| 35 | +Example of a NumPy-style docstring: |
| 36 | + |
| 37 | +```python |
| 38 | +def my_function(param1, param2): |
| 39 | + """Summary of the function's purpose. |
| 40 | +
|
| 41 | + Parameters |
| 42 | + ---------- |
| 43 | + param1 : int |
| 44 | + Description of the first parameter. |
| 45 | + param2 : str |
| 46 | + Description of the second parameter. |
| 47 | +
|
| 48 | + Returns |
| 49 | + ------- |
| 50 | + bool |
| 51 | + Description of the return value. |
| 52 | + """ |
| 53 | + # function body |
| 54 | + return True |
| 55 | +``` |
| 56 | + |
| 57 | +## Pre-commit Hooks |
| 58 | + |
| 59 | +This repository uses pre-commit hooks to ensure code quality and consistency. The following hooks are configured: |
| 60 | + |
| 61 | +* **`ruff-check`**: A linter to check for common errors and style issues. |
| 62 | +* **`ruff-format`**: A code formatter to ensure a consistent code style. |
| 63 | +* **`uv-lock`**: A hook to keep the `uv.lock` file up to date. |
| 64 | + |
| 65 | +Before committing, please ensure that the pre-commit hooks pass. You can run them manually on all files with `pre-commit run --all-files`. |
| 66 | + |
| 67 | +## Documentation |
| 68 | + |
| 69 | +The documentation for this project is built using `quartodoc`. The documentation is automatically built and deployed via GitHub Actions. There is no need to build the documentation manually. |
| 70 | + |
| 71 | +## Type Checking |
| 72 | + |
| 73 | +This project uses `ty` for type checking. To check for type errors, run the following command: |
| 74 | + |
| 75 | +```bash |
| 76 | +uv run ty check src tests |
| 77 | +``` |
0 commit comments