Development#

This project uses Git for version control and uv for Python packaging and environment management.

Ensure both tools are installed and available in your environment.

Configure development environment#

  1. Be sure to have a github account with some SSH key configured (or you won’t be able to push modifications) and that you configured git:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

  1. Clone the repo and enter its root folder:

git clone git@github.com:xdas-dev/xdas.git
cd xdas

  1. Checkout to the dev branch:

git checkout dev

  1. Create virtual environment and install development dependencies:

uv sync --all-groups

  1. Check that all tests are passing and that test coverage is 100%:

uv run pytest --cov

  1. Check that the documentation builds without errors:

cd docs
uv run make html
cd ..

You can then inspect the documentation by opening index.html in docs/_build/html with any browser (see later).

Package structure#

Here a quick overview:

. (general configs file are in the root directory)
├── xdas (python source code are here. Note that there is an xdas folder
│   inside the root folder which is usually also name xdas)
├── docs (everything related to documentation is here)
└── tests (tests are here. This folder mirrors the xdas tree structure with prepended
   test_ to all files).

Adding a function#

Most of the time, you will add functions (or methods) to implement new features. Small internal functions can be quite undocumented but ideally, function that will be used by users requires to:

  • write the body of the function

  • write a docstring that explains how to use the function

  • add an example into the docstring

  • add tests

  • include the function to the documentation

We will go through all the details

How to edit the code#

The usual workflow is:

  • create a branch to have your independent version of the code

  • make modifications by doing as many commits as you want

  • format your code

  • check that the tests are passing (and that the documentation builds).

  • publish your branch online

  • make a pull request to ask the permission to merge your code.

To do this you can either use git in the terminal or within VS Code.

How to write a docstring with examples#

You need to add multiline string that follows the numpydoc style. Here an example:

def your_function(arg1, arg2=None):
   """
   Explain in one line the main objective.

   Add additional information with with as many comments as you wants. You will need to wrap you code (ideally max 88 char per line).

   Parameters
   ----------
   arg1: type (e.g., float)
       Some description.
   arg2: type, optional
       Some description.

   Returns
   -------
   type:
       Some description.

   Examples
   --------
   >>> your_function(1, "value")
   "result"

   """
   return do_something_with_args(arg1, arg2)

Note that the outputs of the examples will be used as tests. pytest will check that the hard coded output matches what the code actually outputs. This is a first quick way to add tests to your function.

How to format your code#

Run (in the root xdas folder or where you are working):

uv run ruff check --fix
uv run ruff format

How to add tests#

pytest is used for testing.

If you are working on a function in a script in xdas/dir/file.py then test must be located in tests/dir/test_file.py. In pytest each test is one function. Each function can check several things with the assert python statement. Functions can be grouped into classes. Bellow an example:

import pytest

class TestMyModule:
   def test_my_function(self): # here self is generally unused
       assert mu_function(0) == 42  # it must be True otherwise the test doesn't pass
       with pytest.raises(ValueError):  # check it raise the correct error
           my_function(-1)

Note that here we have one test class for the entire module (the file.py) but we could have one test class per function if those require to test a lot of things. When testing classes, one testing class per developed class is generally the way to go.

To run and check that your tests are passing:

uv run pytest --cov

Note that VS Code has a nice set of features to run tests.

Editing the documentation#

The documentation is written in markdown.

It uses the MyST syntax to run code as if the documentation was a jupyter notebook.

The simplest is probably to take inspiration from some pre-existing documentation.

If you need some stuff to be run outside some documentation page (e.g. to generate some data) you can place your code at the end of the docs/conf.py file.

To build the documentation go in the docs folder an run:

uv run make html

You can then inspect the documentation by opening index.html in docs/_build/html with any browser.

Note that VS Code has an extension called Live Preview to render html. Once this extension is installed, right click on the index.html file and click on Show preview.