docs: better dev docs (#755)

Signed-off-by: Tomer Figenblat <[email protected]>

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+<!-- markdownlint-disable MD041-->
+## Description
+
+> Describe what you did and why.
+
+## Checklist
+
+- [ ] I have followed this repository's contributing guidelines.
+- [ ] I verified test pass using `tox -e test` (docs modifications require `tox -e docs`).

.gitignore

@@ -134,6 +134,7 @@ dmypy.json
 .env_vars
 
 # coverage reports
+htmlcov
 coverage.xml
 junit.xml
 

CONTRIBUTING.md

@@ -9,65 +9,78 @@
 
 ## Early-access
 
-An early-access image manifest is deployed to [ghcr.io](https://github.com/TomerFi/switcher_webapi/pkgs/container/switcher_webapi)
-for every merge to the default branch, `dev`:
+Early-access image deployed to [GitHub container registry][ghcr]:
 
 ```shell
 docker run -d -p 8000:8000 --name switcher_webapi ghcr.io/tomerfi/switcher_webapi:early-access
 ```
 
-> Note: *ghcr.io* requires *GitHub* login.
+## Project
 
-## Project walkthrough
-
-A [Python](https://www.python.org/) WebApp running inside a container,<br/>
-the documentation site is built with [MkDocs](https://www.mkdocs.org/).
+[Docker][docker] multi-platform image running a [Python][python] web app. The doc site is built with [Mkdocs][mkdocs].
 
 - [app/webapp.py](https://github.com/TomerFi/switcher_webapi/blob/dev/app/webapp.py) the application file
 - [app/tests/](https://github.com/TomerFi/switcher_webapi/tree/dev/app/tests) unit tests
 - [Dockerfile](https://github.com/TomerFi/switcher_webapi/blob/dev/Dockerfile) image instructions
 - [docs](https://github.com/TomerFi/switcher_webapi/tree/dev/docs) sources for the documentation site
 
-The released image is deployed to [Docker Hub](https://hub.docker.com/r/tomerfi/switcher_webapi).
-
-> Note: *Docker Hub* requires login.
+The released image is deployed to [Docker hub][docker_hub].
 
-## Prepare the environment
+## Develop
 
-With [Python >= 3.10](https://www.python.org/) use [pip](https://pypi.org/project/pip/) to install
-[tox](https://tox.readthedocs.io/):
+Run commands using [tox][tox]:
 
 ```shell
-pip install tox
+# Run linters and tests
+tox -e test
+# Generate the docs site
+tox -e docs
+# Serve the docs site
+tox -e docs-serve
 ```
 
-## Build commands
+### Environment
+
+If you need to work inside the development environment, keep reading.
+
+Prepare the environment:
+
+```shell
+tox
+```
 
-- `tox` will execute linting jobs and run python's test cases
-- `tox -e docs` will test and build the documentation site
-- `make` will use `docker buildx` to build the multi-platform image
+Update the environment:
 
-## Code development
+```shell
+tox -r
+```
 
-Activate the development virtual environment (after running `tox`):
+Activate the environment:
 
 ```shell
 source .tox/dev/bin/activate
 ```
 
-Deactivate with:
+Deactivate the environment:
 
 ```shell
 deactivate
 ```
 
-For dependency updates, update the virtual environment:
+### Code
+
+Running tests and linters is done using (pytest takes positional arguments):
 
 ```shell
-tox -r
+# run all tests
+tox -e test
+# run a specific test
+tox -e test -- -k "test_name_goes_here"
 ```
 
-Once inside the virtual environment, you can the various linters:
+If you need to work inside the development environment, [prepare the environment](#environment).
+
+Run the various linters inside the environment:
 
 ```shell
 black --check app/
@@ -77,51 +90,74 @@ mypy --ignore-missing-imports app/
 yamllint --format colored --strict .
 ```
 
-And run the tests:
+Run tests inside the environment:
 
 ```shell
-pytest -v --cov --cov-report term
-pytest -v --cov --cov-report=xml:coverage.xml --junit-xml junit.xml
+# run all tests
+pytest -v
+# run a specific test
+tox -e test -- -k "test_name_goes_here"
+# run tests and print coverage summary to stdout
+pytest -v --cov --cov-report term-missing
+# run tests and create coverage report
+pytest -v --cov --cov-report=html
 ```
 
-## Docs development
+### Docs
 
-Activate the development virtual environment (after running `tox -e docs`):
+Generating or serving the docs is done using:
 
 ```shell
-source .tox/docs/bin/activate
+# generate the docs site
+tox -e docs
+# generate and serve the docs site
+tox -e docs-serve
 ```
 
-Deactivate with:
+If you need to work inside the development environment, [prepare the environment](#environment).
+
+Generate the site inside the environment:
 
 ```shell
-deactivate
+mkdocs build
 ```
 
-For dependency updates, update the virtual environment:
+Generate and serve the site from within the environment:
 
 ```shell
-tox -e docs -r
+tox -e docs-serve
 ```
 
-Once inside the virtual environment, you can build the documentation site:
+### Docker 
 
-```shell
-mkdocs build
-```
+> [!IMPORTANT]  
+> Testing requires [make][make] and [npm][npm].
 
-Or even serve it locally while watching the sources and reloading for modifications:
+Lint the Dockerfile:
 
 ```shell
-mkdocs serve
+make dockerfile-lint
 ```
 
-## Extra linters
+Configure [qemu][qemu] for multi-platform builds:
 
-For CI purposes, we use an extra linter outside the scope of *Python*.
+```shell
+make enable-multiarch
+```
 
-We use use [npm](https://www.npmjs.com/), for linting lint the *Dockerfile*:
+Builds the multi-platform image using `docker buildx`:
 
 ```shell
-make dockerfile-lint
+make build
 ```
+
+<!-- LINKS -->
+[docker]: https://www.docker.com/
+[docker_hub]: https://hub.docker.com/r/tomerfi/switcher_webapi
+[ghcr]: https://github.com/TomerFi/switcher_webapi/pkgs/container/switcher_webapi
+[make]: https://www.gnu.org/software/make/manual/make.html
+[mkdocs]: https://www.mkdocs.org/
+[npm]: https://www.npmjs.com/
+[python]: https://www.python.org/
+[tox]: https://tox.readthedocs.io/
+[qemu]: https://docs.docker.com/build/building/multi-platform/#qemu

README.md

@@ -7,7 +7,7 @@
 [![pages-badge]][pages]
 [![codecov-badge]][codecov]
 
-Gain containerized access to your local [Switcher][switcher] smart devices.
+Gain access to your local [Switcher][switcher] smart devices.
 
 ```shell
 docker run -d -p 8000:8000 --name switcher_webapi tomerfi/switcher_webapi:latest

tox.ini

@@ -1,29 +1,42 @@
 [tox]
-envlist=dev
-skipsdist=True
-
-[testenv]
-basepython = python3.13
+env_list=dev
+no_package=True
 
 [testenv:dev]
+description: Prepare development environment
+deps =
+    -r requirements.txt
+    -r requirements_test.txt
+    -r requirements_docs.txt
+
+[testenv:test]
+description: Run linters and tests
 deps =
-    -rrequirements.txt
-    -rrequirements_test.txt
+    -r requirements.txt
+    -r requirements_test.txt
 commands =
     black --check app/
     flake8 --count --statistics app/
     isort --check-only app/
     mypy --ignore-missing-imports app/
-    pytest -v --cov --cov-report term {posargs}
+    pytest -v --cov --cov-report term-missing {posargs}
     yamllint --format colored --strict .
 
 [testenv:docs]
+description = Generate the docs site (use in CI)
 deps =
-    -rrequirements.txt
-    -rrequirements_docs.txt
+    -r requirements_docs.txt
 commands =
     mkdocs build
 
+# DO NOT RUN IN CI
+[testenv:docs-serve]
+description = Serve the docs site (don't use in CI)
+deps =
+    -r requirements_docs.txt
+commands =
+    mkdocs serve
+
 [flake8]
 max-line-length=88
 per-file-ignores=app/tests/*.py:E501,D103