Development#

This chapter describes how to set up a local development environment for inspect-jitsi and the make targets available while working on it.

Setup#

inspect-jitsi uses a plain Python virtual environment and a Makefile to wrap the common commands.

git clone https://github.com/niccokunzmann/inspect-jitsi
cd inspect-jitsi
make init

make init creates a virtual environment in .venv/ and installs inspect-jitsi into it, editable, together with its test, cli, and docs extras.

Makefile targets#

Target	Description
`make init`	Create the virtual environment and install every extra needed for development.
`make dev`	Alias for `make init`.
`make test`	Run the test suite with `pytest`.
`make lint`	Check for lint issues with `ruff` (same as CI).
`make format`	Format the code base with `ruff` and fix auto-fixable lint issues.
`make dist`	Build the sdist and wheel into `dist/`.
`make clean`	Clean the docs build directory.
`make clean-all`	Clean the docs build directory and the virtual environment.
`make html`	Build the documentation as HTML into `docs/_build/html/`.
`make livehtml`	Rebuild the documentation on changes, with live-reload in the browser.
`make linkcheck`	Check the documentation for broken links.

Trying the CLI on your machine#

Activate the virtual environment make init created, and the inspect-jitsi command runs against this checkout:

source .venv/bin/activate
inspect-jitsi --help

Since it was installed editable (pip install -e), code changes you make take effect immediately, no reinstall needed.

Running the tests#

make test

Equivalent to .venv/bin/pytest. The test suite drives JitsiXmppConnection (and the higher-level wrappers built on it) against a scripted fake XMPP/WebSocket server, rather than a real Jitsi deployment - see inspect_jitsi.test.conftest.

To check for lint issues without fixing them (e.g. what CI runs):

make lint

Building the documentation#

This documentation is built with Sphinx. To build it once as static HTML:

make html

The output is written to docs/_build/html/index.html.

While editing the documentation, run a live-reloading local server instead - it rebuilds and refreshes your browser automatically as you save changes to any .rst file or docstring:

make livehtml

This serves the documentation at http://127.0.0.1:8000 by default.

To check for broken links across the documentation:

make linkcheck

The API reference under Reference is generated automatically from docstrings in the source code via sphinx.ext.apidoc, and the CLI reference from the inspect-jitsi command's own --help output via typer utils docs - there's nothing to keep in sync by hand in either case; just document new modules, classes, functions, and CLI options as you write them.

Releasing#

Pushing a v* git tag builds the package and publishes it to PyPI automatically - see .github/workflows/tests.yml.

Create a version variable:

export VERSION="v0.0.2"

Edit the CHANGES.md at the repository root. Then commit the changes and check that the CI build is running.

git add CHANGES.md
git commit -m"$VERSION"
git push

Once the CI build passes, create a tag and push it.

git tag "$VERSION"
git push origin "$VERSION"

Contributing#

Pull requests are welcome on GitHub. Please make sure make test and make lint pass before opening one - the test suite is what CI runs.