Development and documentation
As we made the choice not to store previous versions of the documentation online, you may want to build a local version of the documentation for the version of the code you are currently using.
To do that you can use the following resources to quickly be able to do it.
Quickly use the source
If you want to build the documentation, only using a virtual environment and the following should be enough. The documentation will be available at doc/_build/html/index.html:
pip install nbsphinx sphinx-autoapi sphinx_rtd_theme cd doc && make html
If you want to test exo_k, only using a virtual environment and the following should be enough:
pip install pytest pytest
If you install exo_k with pip install -e . and you get a message of this kind: ERROR: File “setup.py” or “setup.cfg” not found, you need to upgrade pip:
python -m pip install --upgrade pip
Using Poetry
Whether you want to contribute to exo_k, build the documentation for your local version or ensure that the tests passed, another way is to use poetry to setup your virtual environment. All requirements are listed inside pyproject.toml and poetry.lock. They ensure that everyone use the same dependencies.
After cloning the repository, you only need to execute the following command to create your environment and install the dependencies:
poetry install
After that you can spawn a shell with poetry shell or just run a command with poetry run command.
Documentation
The documentation can be produced with:
cd doc && poetry run make
If you are editing it, you can locally serve it and refreshed on change with the following:
cd doc && poetry run make livehtml
The following extensions can be added to jupyter to match the wanted behavior:
@jlab-enhanced/cell-toolbar
@jupyterlab/celltags
@epi2melabs/jupyterlab-autorun-cells
You can install them using the following syntax:
jupyter-labextension install <extension-name>
Tests
You can easily run the tests with pytest:
poetry run pytest
You can enable a more verbose output with the flag -vv, pytest-clarity provide a better output in this verbose mode.
To run a specific test, just add the path to the test file as an argument.
Tests - Extensive
While pytest allow to test the code, it does not have the ability to manipulate the python version used.
To perform more intensive testing, you can use tox. A list of pre-defined environments allow to test the code for each python version supported. ( You may need to install multiple python version, use: pyenv )
tox
Poetry recap
You can read the documentation of poetry at this address .
You can add a package in the following manner:
poetry add <important-pkg>
poetry add -G dev <pkg-by-the-devs>
After you modify pyproject.toml, to manually add dependencies for example, lock it like that:
poetry lock
To install the environment defined:
poetry install --sync
To choose an other python version:
poetry env use 3.12
poetry install --sync
CI/CD
If you need to check or debug the output of some steps of the pipeline, you can run it manually. You will have the option to set a value to the variable representing what you want to check.
For example, you want the CI to build the documentation. Go to Build>Pipeline: Run pipeline, choose your branch and set a value to DEBUG_DOC, then run it. GitLab will create a pipeline which will create the documentation.