> ## Documentation Index
> Fetch the complete documentation index at: https://touchdeck.codesft.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Work on Touchdeck and its docs locally

## Project layout

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

## Dev environment

**1. Install dev dependencies**

```bash theme={null}
uv venv
uv sync --dev
```

This installs PySide6, qasync, psutil, NVML bindings (optional), Spotipy, and test tools.

**2. Run the app locally**

```bash theme={null}
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**

```bash theme={null}
uv run pytest
```

For coverage:

```bash theme={null}
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**

```bash theme={null}
npm i -g mint
```

**2. Preview docs**

```bash theme={null}
cd docs
mint dev
```

Open [http://localhost:3000](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](../README.md) for user-facing setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.