Update docs workflow and build artifacts

Author: alexlib

.gitignore

@@ -4,6 +4,7 @@ version.py
 # Sphinx automatic generation of API
 docs/README.md
 docs/_api/
+docs/_generated/
 
 # Combined environments
 ci/combined-environment-*.yml

Makefile

@@ -1,6 +1,8 @@
 PROJECT := openptv_python
 CONDA := conda
 CONDAFLAGS :=
+UV := uv
+UVFLAGS := --extra dev --upgrade
 COV_REPORT := html
 PYTHON ?= python
 
@@ -15,11 +17,16 @@ unit-tests:
 type-check:
 	$(PYTHON) -m mypy .
 
+env-update: uv-env-update
+
 conda-env-update:
 	$(CONDA) install -y -c conda-forge conda-merge
 	$(CONDA) run conda-merge environment.yml ci/environment-ci.yml > ci/combined-environment-ci.yml
 	$(CONDA) env update $(CONDAFLAGS) -f ci/combined-environment-ci.yml
 
+uv-env-update:
+	$(UV) sync $(UVFLAGS)
+
 docker-build:
 	docker build -t $(PROJECT) .
 
@@ -30,6 +37,6 @@ template-update:
 	pre-commit run --all-files cruft -c .pre-commit-config-cruft.yaml
 
 docs-build:
-	cp README.md docs/. && cd docs && rm -fr _api && make clean && make html
+	cp README.md docs/. && $(PYTHON) docs/render_native_stress_demo_include.py && cd docs && rm -fr _api && make clean && make html
 
 # DO NOT EDIT ABOVE THIS LINE, ADD COMMANDS BELOW

README.md

@@ -184,17 +184,28 @@ OPENPTV_SKIP_STRESS_BENCHMARKS=1 uv run make
 
 ### Workflow for developers/contributors
 
-For the best experience create a new conda environment (e.g. DEVELOP) with Python 3.12:
+Recommended contributor workflow with `uv`:
 
+```bash
+uv venv
+source .venv/bin/activate
+make env-update
 ```
+
+This keeps the local environment synced to the locked developer dependency set.
+
+If you prefer the conda workflow instead:
+
+```bash
 conda create -n openptv-python -c conda-forge python=3.12
 conda activate openptv-python
+make conda-env-update
 ```
 
 Before pushing to GitHub, use the developer install above and then run the
 following commands:
 
-1. Update conda environment: `make conda-env-update` or `uv venv` and `source .venv/bin/activate` followed by `uv sync --extra dev --upgrade`
+1. Update the environment: `make env-update` by default, or `make conda-env-update` if you are using the conda workflow
 1. If you are using pip instead of uv, install the editable developer environment: `pip install -e ".[dev]"`
 1. Sync with the latest [template](https://github.com/ecmwf-projects/cookiecutter-conda-package) (optional): `make template-update`
 1. Run quality assurance checks: `make qa`