SFTtech · mikonse · Dec 30, 2025 · Dec 30, 2025
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,25 +1,20 @@
-# .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
-    os: ubuntu-20.04
+    os: ubuntu-24.04
     tools:
-        python: "3.9"
+        python: "3.13"
+    jobs:
+        pre_create_environment:
+            - asdf plugin add uv
+            - asdf install uv latest
+            - asdf global uv latest
+        create_environment:
+            - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+        install:
+            - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
     configuration: docs/conf.py
-
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-formats:
-    - pdf
-
-# Optionally declare the Python requirements required to build your docs
-python:
-    install:
-        - requirements: docs/requires.txt
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/_ext/edit_on_github.py b/docs/_ext/edit_on_github.py
diff --git a/docs/conf.py b/docs/conf.py
@@ -26,7 +26,7 @@
 author = "Michael Loipführer, Jonas Jelten, Michael Enßlin"
 copyright = f"{datetime.datetime.now():%Y}, {author}"  # pylint: disable=redefined-builtin
 
-version = abrechnung.__version__.replace(".dirty", "")
+version = abrechnung.__version__
 release = version
 
 # -- General configuration ---------------------------------------------------
@@ -42,9 +42,14 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
-    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+    "myst_parser",
     "sphinxcontrib.openapi",
-    *[p.stem for p in (HERE / "_ext").glob("*.py")],
+]
+myst_enable_extensions = [
+    "colon_fence",
+    "html_image",
+    "attrs_inline",
 ]
 
 # Generate the API documentation when building
@@ -79,11 +84,11 @@
 html_theme_options = dict(navigation_depth=1, titles_only=True)
 github_repo = "abrechnung"
 html_context = dict(
-    display_github=True,  # Integrate GitHub
-    github_user="SFTtech",  # Username
-    github_repo="abrechnung",  # Repo name
-    github_version="master",  # Version
-    conf_py_path="/docs/",  # Path in the checkout to the docs root
+    display_github=True,
+    github_user="SFTtech",
+    github_repo="abrechnung",
+    github_version="master",
+    conf_py_path="/docs/",
 )
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/docs/development/architecture.md b/docs/development/architecture.md
@@ -0,0 +1,7 @@
+# Architecture
+
+TODO
+
+- PostgreSQL DB, exposed as websocket and http REST API
+- various python services (e.g. mail delivery, database cleanup)
+- web-client
diff --git a/docs/development/architecture.rst b/docs/development/architecture.rst
diff --git a/docs/development/contributing.md b/docs/development/contributing.md
@@ -0,0 +1,12 @@
+# Contributing
+
+## As Users
+
+In case you encounter bugs or have ideas for new and useful features don't hesitate to open an
+[issue](https://github.com/SFTtech/abrechnung/issues>) and start a discussion.
+
+## As Developers
+
+Get started by setting up a local [development environment](./setup.md) and reading through the
+[architecture overview](./architecture.rst) and then start hacking.
+[Pull requests](https://github.com/SFTtech/abrechnung/pulls) are always welcome!
diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
diff --git a/docs/development/packaging.md b/docs/development/packaging.md
@@ -0,0 +1,14 @@
+# Packaging
+
+## Debian and Ubuntu
+
+Debian and Ubuntu packages are built by the CI on every push to master and are attached to a new release on every tag
+to master.
+
+To build the packages locally run
+
+```shell
+uv run ./tools/build_debian_packages.py
+```
+
+Docker is a requirement as the packages are built inside a matching docker container for each distribution.
diff --git a/docs/development/packaging.rst b/docs/development/packaging.rst
diff --git a/docs/development/setup.md b/docs/development/setup.md
@@ -0,0 +1,133 @@
+# Setup
+
+```{contents} Table of Contents
+:depth: 2
+```
+
+## Installation
+
+Fork and clone the repository
+
+```shell
+git clone https://github.com/SFTtech/abrechnung.git
+cd abrechnung
+```
+
+Then install the package in local development mode as well as all required dependencies.
+
+Setup a virtual environment and install the packages using uv
+
+```shell
+uv sync
+```
+
+Additionally you probably will want to activate the git pre-commit hooks (for formatting and linting) by running
+
+```shell
+uv run pre-commit install
+```
+
+## Database Setup
+
+Have a running **PostgreSQL** database server.
+Create the database (in a psql prompt):
+
+```sql
+create role someuser with login password 'somepassword';
+create database somedatabasename owner someuser;
+```
+
+- exit the `psql` prompt
+- Copy `config/abrechnung.yaml` to the project root folder and adjust it, e.g. enter someuser, somepassword and somedatabasename
+- Populate database by applying all migrations:
+
+```shell
+uv run abrechnung -c abrechnung.yaml db migrate
+```
+
+- Launch `abrechnung -c abrechnung.yaml api`
+- Launch `abrechnung -c abrechnung.yaml mailer` to get mail delivery (working mail server in config file required!)
+
+It is always possible wipe and rebuild the database with
+
+```shell
+uv run abrechnung -c abrechnung.yaml db rebuild
+```
+
+## Database migrations
+
+In case a new features requires changes to the database schema create a new migration file with
+
+```shell
+uv run sftkit create-migration <revision_name>
+```
+
+In case you did not install the abrechnung in development mode it might be necessary to add the project root folder
+to your `PYTHONPATH`.
+
+## Running tests and linters
+
+To run the tests a dedicated **PostgreSQL** instance is required. The tests assume defaults for the name, user and
+password as
+
+- username: `abrechnung-test`
+- database: `abrechnung-test`
+- password: `asdf1234`
+
+In case you want to use a different database / user they can be overwritten using environment variables:
+
+- `TEST_DB_USER`
+- `TEST_DB_HOST`
+- `TEST_DB_PASSWORD`
+- `TEST_DB_DATABASE`
+
+Make sure the database user has owner permissions on the `public` schema of the database as dropping and recreating
+is used as a means to wipe and repopulate the database between tests.
+
+```sql
+alter schema public owner to "<your user>"
+```
+
+Finally run the tests via
+
+```shell
+make test
+```
+
+Run the linters via
+
+```shell
+make lint
+```
+
+Run the formatters via
+
+```shell
+make format
+```
+
+## Frontend Development
+
+Working on the frontend is quite easy, simply
+
+```shell
+npm install
+npx nx serve web
+```
+
+and you are good to go!
+
+## Documentation
+
+To build the documentation locally simply run
+
+```shell
+pip install -r docs/requires.txt
+make docs
+```
+
+The html docs can then be found in `docs/_build` or served locally with
+
+```shell
+make serve-docs
+```