Rationalize optional dependencies vs dependency groups

Establish clear separation between user-facing optional dependencies
and developer-only dependency groups:

**Optional Dependencies (user features):**
- watcher: File watching service for batch processing
- webservice: Streamlit-based web UI
- Installable via: uv sync --extra <name> or pip install ocrmypdf[name]

**Dependency Groups (developer tools):**
- test: Testing infrastructure (merged from test + extended_test)
- docs: Documentation building tools
- streamlit-dev: Enhanced Streamlit development tools
- dev: General development tools (mypy, ipykernel)
- Installable via: uv sync --group <name> (uv only, NOT pip)

Breaking changes for developers:
- pip install -e .[test] no longer works → use uv sync --group test
- pip install -e .[docs] no longer works → use uv sync --group docs
- pip install -e .[extended_test] removed → merged into test group

No breaking changes for end users:
- pip install ocrmypdf[watcher] still works
- pip install ocrmypdf[webservice] still works

Updated:
- CI/CD workflows to use uv sync --group test
- Docker images to exclude test dependencies
- Documentation to recommend uv with pip as fallback
- pyproject.toml with clear comments explaining both systems

docs/batch.md

@@ -117,6 +117,10 @@ tend to give better performance. watcher.py works on all platforms.
 Users may need to customize the script to meet their requirements.
 
 :::{code} bash
+# Using uv (recommended)
+uv sync --extra watcher
+
+# Or using pip
 pip3 install ocrmypdf[watcher]
 
 env OCR_INPUT_DIRECTORY=/mnt/input-pdfs \

docs/installation.md

@@ -686,18 +686,71 @@ need to be installed. The script requires specific versions of the
 dependencies. Older version than the ones mentioned in the release notes
 are likely not to be compatible to OCRmyPDF.
 
+## Optional Features
+
+OCRmyPDF provides optional features and development tools. We recommend using `uv` as your package manager.
+
+### Installing User Features
+
+User features are available as optional dependencies. Install them with `uv` (recommended) or `pip`:
+
+```bash
+# Using uv (recommended)
+uv sync --extra watcher        # File watching service
+uv sync --extra webservice     # Streamlit web UI
+uv sync --extra watcher --extra webservice  # Multiple features
+
+# Using pip (also works)
+pip install ocrmypdf[watcher]
+pip install ocrmypdf[webservice]
+pip install ocrmypdf[watcher,webservice]
+```
+
+### Development Tools (uv only)
+
+Development tools use dependency groups and require `uv`:
+
+```bash
+# Testing infrastructure
+uv sync --group test
+
+# Documentation building
+uv sync --group docs
+
+# Enhanced Streamlit development
+uv sync --group streamlit-dev
+
+# All development groups
+uv sync
+```
+
+:::{note}
+**User features** (`watcher`, `webservice`) work with both `uv` and `pip`.
+**Developer tools** (`test`, `docs`, `streamlit-dev`) require `uv` and use dependency groups (PEP 735).
+:::
+
+**Why use uv?**
+
+- Modern, fast Python package manager
+- Required for development (testing, docs)
+- Better dependency resolution
+- Consistent across all platforms
+
+Install uv: `pip install uv` or visit https://docs.astral.sh/uv/
+
 ### For development
 
 To install all of the development and test requirements:
 
 ```bash
 git clone -b main https://github.com/ocrmypdf/OCRmyPDF.git
-python -m venv .venv
-source .venv/bin/activate
 cd OCRmyPDF
-pip install -e .[test]
+pip install uv  # Install uv if not already installed
+uv sync --group test
 ```
 
+Note: Development requires `uv`. The old `pip install -e .[test]` method is no longer supported.
+
 To add JBIG2 encoding, see {ref}`jbig2`.
 
 ## Shell completions