Development

Initial setup

Fork the repository on Github, then clone the fork:

git clone git@github.com:YourGithubUserName/bartz.git
cd bartz

Install R and uv (for example, with Homebrew do brew install r uv). Then run

make setup

to set up the Python and R environments.

The Python environment is managed by uv. To run commands that involve the Python installation, do uv run <command>. For example, to start an IPython shell, do uv run ipython. Alternatively, do source .venv/bin/activate to activate the virtual environment in the current shell.

The R environment is automatically active when you use R in the project directory.

Pre-defined commands

Development commands are defined in a makefile. Run make without arguments to list the targets.

Benchmarks

The benchmarks are managed with asv. The basic asv workflow is:

uv run asv run      # run and save benchmarks on main branch
uv run asv publish  # create html report
uv run asv preview  # start a local server to view the report

asv run writes the results into files saved in ./benchmarks. These files are tracked by git; consider deliberately not committing all results generated while developing.

There are a few make targets for common asv commands. The most useful command during development is

make asv-quick ARGS='--bench <pattern>'

This runs only benchmarks whose name matches <pattern>, only once, within the working copy and current Python environment.

Documentation

To build the documentation for the current working copy, do

make docs

To build the documentation for the latest release tag, do

make docs-latest

To debug the documentation build, do

make docs SPHINXOPTS='--fresh-env --pdb'