Skip to main content

​
Project layout

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

​
Dev environment

1

Install dev dependencies

uv venv
uv sync --dev
This installs PySide6, qasync, psutil, NVML bindings (optional), Spotipy, and test tools.
2

Run the app locally

uv run touchdeck
# or: python -m touchdeck
Use --display flags? Not needed—the app prompts you to pick a screen on first launch.
3

Run tests

uv run pytest
For coverage:
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

1

Install the Mintlify CLI

npm i -g mint
2

Preview docs

cd docs
mint dev
Open http://localhost:3000 to view the docs.

​
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
See README for user-facing setup.