docs/contribution/dev_container.md (new file)			docs/contribution/dev_container.md @ PR head
t			t	1	# Dev Container and Codespaces
				2
				3	The repository ships a
				4	[`.devcontainer/devcontainer.json`](https://github.com/mozarkai/optics-framework/blob/main/.devcontainer/devcontainer.json)
				5	that builds a ready-to-work environment: Python 3.12, Poetry, the project's
				6	dependencies, the pre-commit hooks, and the editor extensions the project
				7	lints with. Use it instead of the manual setup in the
				8	[Developer Guide](developer_guide.md) if you would rather not install a
				9	toolchain on your machine, or if you want a throwaway environment for a
				10	one-off contribution.
				11
				12	## Opening it
				13
				14	**GitHub Codespaces** — on the repository page, **Code → Codespaces → Create
				15	codespace**. Nothing to install locally.
				16
				17	**VS Code, locally** — install the
				18	[Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
				19	extension and Docker, clone the repository, then run **Dev Containers: Reopen
				20	in Container** from the command palette.
				21
				22	Either way the first start runs the container's setup command, which installs
				23	the system libraries the vision engines need (`libgl1`, `libglib2.0-0`), a
				24	headless JRE, the Poetry environment (`poetry install`, which includes the
				25	`dev`, `test` and `docs` groups), and the pre-commit hooks. It takes a few
				26	minutes; afterwards the usual commands work without a prefix beyond `poetry
				27	run`:
				28
				29	```bash
				30	poetry run pytest
				31	poetry run ruff check --fix .
				32	poetry run pre-commit run --all-files
				33	poetry run mkdocs serve
				34	```
				35
				36	## What you get
				37
				38	| | |
				39	|---|---|
				40	| **Base image** | `mcr.microsoft.com/devcontainers/python:1-3.12-bullseye` |
				41	| **Tooling** | Poetry, git, Docker CLI (talking to the host daemon), scancode-toolkit |
				42	| **Editor** | Pylance, Ruff, Pylint, markdownlint, YAML, Docker, Conventional Commits |
				43	| **Testing** | pytest enabled as the VS Code test runner |
				44
				45	Docker is wired as *docker-outside-of-docker*, so `docker build` and
				46	`docker compose` inside the container drive the host's daemon — the images in
				47	[Docker Deployment](../usage/docker_deployment.md) build from here as they
				48	would from a normal shell.
				49
				50	## What it does not give you
				51
				52	The container has no Android SDK, no emulator, and no Appium server, so it is
				53	a **development** environment rather than a test-execution one. To run a suite
				54	against a real target from inside it, point `config.yaml` at an Appium server
				55	reachable over the network. For one on the host machine, the container is
				56	started with a `host.docker.internal` host entry, so:
				57
				58	```yaml
				59	driver_sources:
				60	- appium:
				61	enabled: true
				62	url: "http://host.docker.internal:4723"
				63	```
				64
				65	A Codespace has no route to your local machine at all — use a remote Appium
				66	grid, or work on code, docs and unit tests there and run device suites
				67	locally.

Legends
Colors Added Changed Deleted	Links (f)irst change (n)ext change (t)op