Development

​

Project layout

• App code: touchdeck/
• Tests: tests/
• Docs (this site): docs/
• Settings + caches at runtime: ~/.config/touchdeck/

​

Dev environment

uv venv
uv sync --dev

uv run touchdeck
# or: python -m touchdeck

uv run pytest

uv run pytest --cov --cov-branch --cov-report=xml --cov-report html:cov_html

​

Code style and linting

• The codebase is type-hinted; prefer mypy-friendly changes.
• Keep UI styles consistent with touchdeck/themes.py and widget helpers.
• Avoid blocking the Qt event loop—use asyncio.to_thread where needed.

​

Working on docs

npm i -g mint

cd docs
mint dev

​

Where to contribute

• New UI pages or widgets: touchdeck/ui/
• Media providers: touchdeck/services/mpris.py, touchdeck/services/spotify_provider.py
• Settings and validation: touchdeck/settings.py
• Quick actions and custom commands: touchdeck/quick_actions.py and touchdeck/ui/window.py