add CONTRIBUTING file generation

.github/workflows/check-generated-files.yml

@@ -0,0 +1,23 @@
+name: Check generated files
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check-generated:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run generation script
+        run: scripts/github_generate.sh
+
+      - name: Check for uncommitted changes
+        run: git diff --exit-code

scripts/contributing/build_docs.md

@@ -0,0 +1,23 @@
+## Build documentation
+
+The documentation is built with [Sphinx](https://www.sphinx-doc.org/en/master/) that generates HTML pages out of the RST files. The configuration of Sphinx is in `doc/conf.py`.
+
+Requirements (including Sphinx) can be installed with
+
+```bash
+pip install .[doc]
+```
+
+Then, build the documentation with
+
+```bash
+sphinx-build doc build/sphinx/html -E -a
+```
+
+The generated HTML pages will be available in `build/sphinx/html`. You can browse them by opening `build/sphinx/html/index.html` in your browser.
+
+When rebuilding the documentation, don't forget to remove generated files to have a fresh `autodoc` documentation:
+
+```bash
+rm -rf doc/_generated/; sphinx-build doc build/sphinx/html -E -a
+```

scripts/contributing/formatting_black.md

@@ -0,0 +1,5 @@
+## Formatting
+
+All code must be formatted with [black](https://black.readthedocs.io/en/stable) latest version or the CI will break. Editor integration such as [Black VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) or [Git hooks](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) can be set-up for automatic formatting.
+
+The configuration can be found in `pyproject.toml`.

scripts/contributing/formatting_ruff.md

@@ -0,0 +1,7 @@
+## Formatting
+
+[ruff](https://docs.astral.sh/ruff/) is used to format the code. It gives formatting equivalent to [black](https://docs.astral.sh/ruff/faq/#how-does-ruffs-formatter-compare-to-black).
+
+Editor integration such as [Ruff VSCode extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) or [Git hooks](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) can be set-up for automatic formatting.
+
+The configuration can be found in `pyproject.toml` under `[tool.ruff.format]` sections.

scripts/contributing/getting_started.md

@@ -0,0 +1,7 @@
+## Getting started
+
+Requirements are listed in `pyproject.toml` and can be installed with
+
+```bash
+pip install [--user] .[dev]
+```

scripts/contributing/imports_isort.md

@@ -0,0 +1,5 @@
+## Import order
+
+Order of imports is enforced by [isort](https://pycqa.github.io/isort/). Same as for black, editor extensions such as [isort VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.isort) can be used to sort imports automatically when saving.
+
+The configuration in `pyproject.toml` is made to be [compatible with black](https://pycqa.github.io/isort/docs/configuration/black_compatibility.html).

scripts/contributing/imports_ruff.md

@@ -0,0 +1,12 @@
+## Import order
+
+Order of imports is enforced by [ruff](https://docs.astral.sh/ruff/) **linter**. The [imports can be automatically sorted](https://docs.astral.sh/ruff/formatter/#sorting-imports) by running:
+
+```bash
+ruff check --select I --fix
+ruff format
+```
+
+As for formatting, we advise to use the [Ruff VSCode extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) or [a Git hook](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) to sort imports automatically when saving.
+
+Configuration can be found in `pyproject.toml` under `[tool.ruff.lint.isort]` sections.

scripts/contributing/linting_flake8.md

@@ -0,0 +1,5 @@
+## Linting
+
+[flake8](https://flake8.pycqa.org/en/latest/index.html) is used to lint the code.
+
+The configuration is located in `.flake8`. It is written specifically to be compatible with black so that changes should not be needed. If needed, linting errors can be [ignored inline by adding comments](https://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors) (e.g.`# noqa: E123`).

scripts/contributing/linting_ruff.md

@@ -0,0 +1,5 @@
+## Linting
+
+[ruff](https://docs.astral.sh/ruff/) is used to lint the code. The linting is equivalent to [flake8](https://docs.astral.sh/ruff/faq/#how-does-ruffs-linter-compare-to-flake8) linting.
+
+[Configuration](https://docs.astral.sh/ruff/configuration/) can be changed in `pyproject.toml` but the default configuration is compatible with black so that changes should not be needed. If needed, linting errors can be [ignored inline by adding comments](https://docs.astral.sh/ruff/linter/#line-level) (e.g.`# noqa: E123`).

scripts/contributing/releasing.md

@@ -0,0 +1,43 @@
+## Releasing
+
+1. Checkout `main` and verify that it is up to date with the server and that your working tree is clean.
+
+1. Add the [changes](https://changelog.md) to `CHANGELOG.md` under a version number that matches the
+   [regex pattern](https://regex101.com/r/Ly7O1x/3/) provided by the [semantic versioning](https://semver.org)
+   guidelines. For example the lifecycle of a single version could be
+
+   ```
+   1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
+   ```
+
+1. Change the version number in `<project>/pyproject.toml` to the version number put in the CHANGELOG.
+
+1. Push your changes to a branch and create a MR to merge your changes in `main`.
+
+1. Deploy the project using one of the two methods below:
+
+   - Deploy through CI jobs (recommended)
+
+      Once the tests have passed on `main`, CI jobs for deployment on [pypi](https://pypi.org) and [testpypi](https://test.pypi.org)
+      will be available in the CI pipeline page. Launching these jobs manually will trigger the deployment on the corresponding
+      python package index. In case of the `pypi` job a git tag for the version will be added to the repository.
+
+   - Deploy manually from the terminal with `build` and `twine`
+
+      ```bash
+      rm -rf dist
+      pip install build
+      python3 -m build -s
+      twine upload -r testpypi dist/*
+      twine upload -r pypi dist/*
+      ```
+
+1. A git tag for the version is created automatically when deploying through the `pypi` CI job. Manual deployment however
+   requires manual tagging
+
+   ```bash
+   git tag v1.2.3
+   git push && git push --tags
+   ```
+
+   Release notes can be added in the `Tags` page of the gitlab repository.

scripts/contributing/testing.md

@@ -0,0 +1,13 @@
+## Testing
+
+Tests make use [pytest](https://docs.pytest.org/en/stable/index.html) and can be run as follows
+
+```bash
+pytest .
+```
+
+Testing an installed project is done like this
+
+```bash
+pytest --pyargs <project_name>
+```

scripts/contributing/write_docs.md

@@ -0,0 +1,5 @@
+## Write documentation
+
+The documentation is composed of RST files located in `doc`. You can look at the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) for information on how to write RST files.
+
+If a new file is created, don't forget to reference it in one of the `toctree` directive.

scripts/github_contributing.py

@@ -0,0 +1,60 @@
+from pathlib import Path
+
+if __name__ == "__main__":
+
+    thisdir = Path(__file__).parent
+
+    sections = thisdir / "contributing"
+
+    GETTING_STARTED = (sections / "getting_started.md").read_text()
+    TESTING = (sections / "testing.md").read_text()
+    WRITE_DOCS = (sections / "write_docs.md").read_text()
+    BUILD_DOCS = (sections / "build_docs.md").read_text()
+    RELEASING = (sections / "releasing.md").read_text()
+
+    FORMATTING_BLACK = (sections / "formatting_black.md").read_text()
+    LINTING_FLAKE8 = (sections / "linting_flake8.md").read_text()
+    IMPORTS_ISORT = (sections / "imports_isort.md").read_text()
+
+    FORMATTING_RUFF = (sections / "formatting_ruff.md").read_text()
+    LINTING_RUFF = (sections / "linting_ruff.md").read_text()
+    IMPORTS_RUFF = (sections / "imports_ruff.md").read_text()
+
+    default_contributing = (
+        GETTING_STARTED
+        + "\n"
+        + FORMATTING_BLACK
+        + "\n"
+        + LINTING_FLAKE8
+        + "\n"
+        + IMPORTS_ISORT
+        + "\n"
+        + TESTING
+        + "\n"
+        + WRITE_DOCS
+        + "\n"
+        + BUILD_DOCS
+        + "\n"
+        + RELEASING
+    )
+
+    ruff_contributing = (
+        GETTING_STARTED
+        + "\n"
+        + FORMATTING_RUFF
+        + "\n"
+        + LINTING_RUFF
+        + "\n"
+        + IMPORTS_RUFF
+        + "\n"
+        + TESTING
+        + "\n"
+        + WRITE_DOCS
+        + "\n"
+        + BUILD_DOCS
+        + "\n"
+        + RELEASING
+    )
+
+    (thisdir.parent / "shared" / "CONTRIBUTING.md").write_text(default_contributing)
+    (thisdir.parent / "shared" / "CONTRIBUTING_ruff.md").write_text(ruff_contributing)

scripts/github_generate.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+python ./scripts/github_contributing.py

shared/CONTRIBUTING.md

@@ -3,26 +3,26 @@
 Requirements are listed in `pyproject.toml` and can be installed with
 
 ```bash
-pip install .[dev]
+pip install [--user] .[dev]
 ```
 
 ## Formatting
 
 All code must be formatted with [black](https://black.readthedocs.io/en/stable) latest version or the CI will break. Editor integration such as [Black VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) or [Git hooks](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) can be set-up for automatic formatting.
 
-The configuration can be found in `pyproject.toml`. 
+The configuration can be found in `pyproject.toml`.
 
 ## Linting
 
-[flake8](https://flake8.pycqa.org/en/latest/index.html) is used to lint the code. 
+[flake8](https://flake8.pycqa.org/en/latest/index.html) is used to lint the code.
 
 The configuration is located in `.flake8`. It is written specifically to be compatible with black so that changes should not be needed. If needed, linting errors can be [ignored inline by adding comments](https://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors) (e.g.`# noqa: E123`).
 
 ## Import order
 
 Order of imports is enforced by [isort](https://pycqa.github.io/isort/). Same as for black, editor extensions such as [isort VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.isort) can be used to sort imports automatically when saving.
 
-The configuration in `pyproject.toml` is made to be [compatible with black](https://pycqa.github.io/isort/docs/configuration/black_compatibility.html). 
+The configuration in `pyproject.toml` is made to be [compatible with black](https://pycqa.github.io/isort/docs/configuration/black_compatibility.html).
 
 ## Testing
 
@@ -88,9 +88,9 @@ rm -rf doc/_generated/; sphinx-build doc build/sphinx/html -E -a
 
    - Deploy through CI jobs (recommended)
 
-      Launch the `Release` pipeline can manually confirm the steps for 
-      deployment on [pypi](https://pypi.org) and [testpypi](https://test.pypi.org)
-      When the `pypi` job succeeds a git tag for the version will be added to the repository.
+      Once the tests have passed on `main`, CI jobs for deployment on [pypi](https://pypi.org) and [testpypi](https://test.pypi.org)
+      will be available in the CI pipeline page. Launching these jobs manually will trigger the deployment on the corresponding
+      python package index. In case of the `pypi` job a git tag for the version will be added to the repository.
 
    - Deploy manually from the terminal with `build` and `twine`
 
@@ -109,3 +109,5 @@ rm -rf doc/_generated/; sphinx-build doc build/sphinx/html -E -a
    git tag v1.2.3
    git push && git push --tags
    ```
+
+   Release notes can be added in the `Tags` page of the gitlab repository.