📝(project) add demo GIFs that run examples

Thanks to VHS, we now script every documentation example by generating a
GIF that shows the command output.

Author: jmaupetit

CONTRIBUTING.md

@@ -0,0 +1 @@
+docs/guidelines.md

Makefile

@@ -1,6 +1,12 @@
 # -- General
 SHELL := /bin/bash
 
+# -- Docs
+DOCS_TAPES_PATH = scripts/docs
+DOCS_GIFS_PATH  = docs/img/tapes
+DOCS_TAPES      = $(wildcard $(DOCS_TAPES_PATH)/*.tape)
+DOCS_GIFS       = $(addprefix $(DOCS_GIFS_PATH)/,$(patsubst %.tape,%.gif,$(notdir $(DOCS_TAPES))))
+
 # ==============================================================================
 # RULES
 
@@ -9,6 +15,11 @@ default: help
 docs/openapi.json:
 	uv run onzr openapi > docs/openapi.json
 
+$(DOCS_GIFS_PATH)/%.gif: $(DOCS_TAPES_PATH)/%.tape 
+	@echo -e "---\n📼 $< → $@"
+	# Unset MAILCHECK to avoid notification in generated GIFs
+	unset MAILCHECK; uv run vhs $< -o $@
+
 # -- Build
 bootstrap: ## bootstrap the project for development
 bootstrap: \
@@ -20,6 +31,11 @@ build: ## install project
 	uv sync --locked --all-extras --dev
 .PHONY: build
 
+docs-gifs: ## compile all tapes included in the docs
+docs-gifs: $(DOCS_GIFS)
+	@echo "✅ Documentation GIFs updated"
+.PHONY: docs-gifs
+
 docs-serve: ## run documentation server 
 	# Force OpenAPI schema generation
 	uv run onzr openapi > docs/openapi.json

README.md

@@ -10,6 +10,8 @@
     This project is still at an early stage. It works in its core parts, but
     will not meet standard requirements for a decent player.
 
+![Onzr Demo VHS](https://vhs.charm.sh/vhs-6cGaxSq0RKCq7ELvYDItWy.gif)
+
 ## Requirements
 
 - [Python](https://www.python.org): 3.11+

docs/commands.md

@@ -5,6 +5,7 @@ Contributing to Onzr requires the following dependencies to be installed:
 - [GNU Make](https://www.gnu.org/software/make/)
 - [`uv`](https://docs.astral.sh/uv/)
 - [VLC](https://www.videolan.org/vlc/)
+- [VHS](https://github.com/charmbracelet/vhs)
 
 !!! Note