Contributing

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, 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:

    git clone git@github.com:saleae/mso-api.git
cd mso-api

  2. Create a virtual environment using uv and activate it:

    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:

    uv sync --all-extras

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

These can be downloaded from National Instruments here.

  1. 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 for code linting and formatting. To auto-format your code (do before each commit):

ruff format

To lint:

ruff check .

Testing#

We use pytest for testing. To run the tests:

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:

uv sync --all-extras

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

  1. Build the HTML documentation:

python build_docs.py --clean

This will generate HTML documentation in the docs/_build/html directory.

  1. To also build a PDF version:

python build_docs.py --pdf

  1. 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.

Contents