Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
124 lines (81 loc) · 2.73 KB

CONTRIBUTING.md

File metadata and controls

124 lines (81 loc) · 2.73 KB
Raw

Contributing to Sphinx VHS

Set up your environment

We use uv and poe to run tasks, but it is possible to use pure pip as well.

Using pip

  1. Create a virtual environment with python 3.13 or newer (some of dev tools don't work with older pythons).

  2. Make sure your pip is up to date:

    pip install -U pip

  3. Install Sphinx VHS in development mode, and install dev dependencies:

    pip install -e . --group dev

  4. Install pre-commit hooks:

    prek install

  5. Install poe, either globally or in virtual environment:

    pip install poethepoet

Using uv

  1. Sync your virtual environment:

    uv sync

  2. Install pre-commit hooks:

    uv run prek install

  3. Install poe if you don't have it already:

    uv tool install poethepoet

Run commands

We use poe for most of the tasks:

poe lint  # Lint and fix code style.
poe test  # Run tests.
poe test-all  # Run tests for all pythons.

You can see all commands in poe's help:

poe --help

Build docs

To build docs, you'll need to install a latest VHS release. If you run linux, vhs (the python wrapper) will download the binaries for you, otherwise you will have to install it yourself. Note that if you're running WSL or other system that doesn't have a browser, you might need to install additional packages:

sudo apt-get update
sudo apt-get install -y \
    libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
    libxkbcommon0 libxdamage1 libgbm1 libpango1.0-0 libasound2

After that, use poe commands:

poe doc  # Build HTML.
poe doc-watch  # Run sphinx-autobuild.

The first build will take a couple of minutes to record terminal GIFs.

Release

  1. Update CHANGELOG.md.

    Changelog must have a section for the new release, otherwise the build will fail.

  2. Push a git tag. You'll need a repository admin role to do so.

    All tags should start with prefix v, and follow semantic versioning guidelines. This, among other things, means that tags for beta-, post-, etc. releases should have form v1.0.0-beta0 instead of Python's v1.0.0b0.

    You can use poe release to bump the version, create the release commit, and tag it in one step.

  3. From here, release happens automatically. PyPi package will be uploaded from CI job, and documentation will be updated by Read the Docs build.