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

## Jupyter Book

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

To build the documentation locally,
you need to create a Jupyter kernel named `itables` with
```shell
python -m ipykernel install --name itables --user
```
Then you can build the documentation with
```
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
```
pixi run jupyter lab
```
or if you're already in a pixi 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
```