# Developing ITables

In this page you will find instructions on how to
create a development environment and how
to test your changes.

## How to create a development environment

This project uses [pixi](https://pixi.sh) for dependency management. First, install `pixi>=0.60.0` by following the instructions at https://pixi.sh.

Then, activate ITables' development environment with:
```shell
pixi shell
```

Install the pre-commit hooks with
```shell
pre-commit install
```

## How to run the Python test suite

The Python code can be tested with just

```shell
pytest
```

Running the `pytest` test suite is not enough to guarantee that a change won't
break `itables`. You also need to test that the tables are well rendered in the
different contexts like Jupyter Book, Jupyter Lab, VS Code.

### Browser-based (Playwright) tests

A few regressions (e.g. dark mode issues) can only be caught by actually
rendering a table in a browser and inspecting the resulting DOM/CSS. These
tests live under `tests/playwright/` and are skipped when Playwright and its
browser binaries are not installed, since they are not part of the standard
test dependencies. Run them locally with the dedicated `playwright` pixi
environment:

```shell
pixi run -e playwright playwright install chromium
pixi run -e playwright pytest tests/playwright
```

This environment has its own CI job (`pytest-playwright`), so these tests do
run on every push and pull request, in addition to being run locally
whenever you touch the dark-mode or FixedColumns related CSS/JS.

### Reproducing Quarto-specific issues

Quarto's Bootstrap-based HTML theme can interact with the ColumnControl
CSS in ways that a plain notebook render won't reveal (see `#536`). Render
`docs/quarto/quarto_column_control.qmd` with the dedicated `quarto` pixi
environment to reproduce and check such issues:

```shell
pixi run -e quarto quarto render docs/quarto/quarto_column_control.qmd
```

## How to build the package locally

Build both the wheel and source distribution with:

```shell
pixi run -e build hatch build
```

The build artifacts are created in `dist/`.

This uses the dedicated `build` pixi environment, which pins `hatch` and
`virtualenv` to versions that are currently compatible with the
`jupyter-builder` build hook.

## Jupyter Book

The `itables` documentation uses [Jupyter Book](https://jupyterbook.org/).

Build the documentation with:
```shell
pixi run -e docs jupyter book build docs
```

This will give you a link to a local version of the documentation.

If you make any significant change then you should go through
the updated documentation and make sure all the examples
still work properly.

## Jupyter Lab

In the pixi environment, you can start Jupyter with
```shell
pixi run jupyter lab
```
or if you're already in a pixi shell:
```shell
jupyter lab
```

You should test at least this code snippet:
```python
import itables

# try both connected=False (the default) and connected=True
itables.init_notebook_mode(connected=False)

itables.sample_dfs.get_countries(html=True)
```

You can do this using for instance the notebook at `tests/test_notebook.ipynb`.

Note that you can also open the documentation in Jupyter:
go to the `docs` folder and open any `.md` file _as a notebook_ (using a right click).

## Other notebook editors

If you change anything related to the Javascript/HTML code,
you should test the [supported editors](supported_editors.md)
in both the connected and offline mode.

For the online editors like [Google Colab](https://colab.research.google.com/),
you might have to install your development version there with e.g.
```
!pip uninstall itables -y
!pip install git+https://github.com/mwouts/itables.git@branch
```