# Contributing

Thank you for your interest in contributing to the Saleae MSO API! This guide will help you get started with contributing to the project.

## Prerequisites

Install the `uv` package manager. Their [installation instructions are here](https://docs.astral.sh/uv/getting-started/installation/), but the quick version may be to just do:

```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

## Development Setup

1. Clone the repository:
   ```bash
   git clone git@github.com:saleae/mso-api.git
   cd mso-api
   ```

2. Create a virtual environment using `uv` and activate it:
   ```bash
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. Install the package in development mode with the development (`dev`) dependencies into your virtualenv:
   ```bash
   uv sync --all-extras
   ```

4. Install VISA drivers on your machine to run instrument-dependent tests

These can be downloaded from [National Instruments here](https://www.ni.com/en/support/downloads/drivers/download.ni-visa.html).

5. Run the test suite

 - Plug in a Siglent function generator to your machine over USB
 - Plug the MSO into your machine
 - Supply power to the MSO's power USB-C port
 - Using a BNC to SMB cable (or a BNC cable with the MSO's included BNC-to-SMB adapter), plug both channels of the signal generator directly into the MSO's first two channels (CH1 to CH1, CH2 to CH2)
 - Run the test suite
```
uv run pytest tests
```
Or
```
.venv\Scripts\activate  # VSCode wil typically do this automatically with the Python extension installed
pytest tests
```

## Code Style

We use [ruff](https://github.com/charliermarsh/ruff) for code linting and formatting. To auto-format your code (do before each commit):

```bash
ruff format
```

To lint:

```bash
ruff check .
```

## Testing

We use pytest for testing. To run the tests:

```bash
pytest tests
```

## Documentation

This project uses Jupyter Book for documentation. The documentation includes:

- Getting started guide
- Installation instructions
- Usage examples
- API reference
- Contributing guidelines

Building the docs cleanly currently requires an MSO attached to your system, as many of the code examples
in the docs run live on hardware to get capture objects. They will build without an MSO, but the examples
that do both run and depend on hardware will have tracebacks printed right after them.

To build the documentation:

1. Install the development dependencies:

```bash
uv sync --all-extras

# first time installation of the PDF generator requires this
playwright install
```

2. Build the HTML documentation:

```bash
python build_docs.py --clean
```
   This will generate HTML documentation in the `docs/_build/html` directory.

3. To also build a PDF version:
```bash
python build_docs.py --pdf
```

4. The documentation will be available at:
   - HTML: `docs/_build/html/index.html`
   - PDF: `docs/_build/pdf/book.pdf` (if built with `--pdf`)


## Pull Request Process

1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Make your changes
4. Run the tests to ensure they pass
5. Update the documentation if necessary
6. Submit a pull request

## Reporting Issues

If you find a bug or have a feature request, please open an issue on the GitHub repository. Please include:

- A clear and descriptive title
- A detailed description of the issue or feature request
- Steps to reproduce the issue (if applicable)
- Expected behavior
- Actual behavior
- Any relevant logs or screenshots

## Code of Conduct

Please be respectful and considerate of others when contributing to this project. We strive to maintain a welcoming and inclusive environment for all contributors.