Export Poetry's lockfile as pip requirements.txt

This will let the pre-commit hooks ensure
that Poetry's lockfile is kept up-to-date
and that it is exported to a pip `requirements.txt` file.

GitHub: fix #1268

Author: fabcor-maxiv

.pre-commit-config.yaml

@@ -13,9 +13,32 @@ repos:
           - --strict
 
   - repo: https://github.com/python-poetry/poetry
-    rev: 1.5.0
+    rev: 1.8.3
     hooks:
+
+      # Equivalent to running `poetry check --lock`.
+      # This checks that:
+      # 1. the Poetry content of the `pyproject.toml` file is valid;
+      # 2. there is a `poetry.lock` file;
+      # 3. the content of `poetry.lock` is in sync with the content of `pyproject.toml`.
       - id: poetry-check
+        args:
+          - --lock
+
+      # Equivalent to running `poetry lock --no-update`.
+      # This syncs the `poetry.lock` file with the content of the `pyproject.toml` file.
+      # This hook fails if it results in modifying `poetry.lock`.
+      - id: poetry-lock
+        args:
+          - --no-update
+
+  # Equivalent to running `poetry export`.
+  # This exports the `poetry.lock` file to the `requirements.txt` file.
+  # This hook fails if it results in modifying `requirements.txt`.
+  - repo: https://github.com/python-poetry/poetry-plugin-export
+    rev: 1.8.0
+    hooks:
+      - id: poetry-export
 
   - repo: https://github.com/myint/autoflake
     rev: v1.6.0

docs/source/dev/deployment.md

@@ -34,6 +34,9 @@ Some might prefer to use a dedicated installer tool, like pip for such a task.
 
 But Poetry's lockfile format is not standardized, its content is specific to Poetry.
 So this file is not immediately usable by other installers and tools.
+For example pip can not understand `poetry.lock` and completely ignores it.
+When running a command like `pip install mxcubeweb`
+it will NOT choose the versions pinned in `poetry.lock`.
 
 To circumvent this, one could use a command like `poetry export`
 to generate a `requirements.txt` file compatible with pip (and some other tools).
@@ -45,9 +48,14 @@ it should be possible to approximate the behaviour of installing with Poetry's l
     poetry export --format=requirements.txt > requirements.txt
     ```
 
+    Note that the pre-commit hooks are configured to automatically
+    generate an exported `requirements.txt` file and keep it in sync with `poetry.lock`.
+    So this step could be skipped.
+
 1. Move the `requirements.txt` file to the deployment target system
 
-1. On the deployment system, let pip install {{project}} via the exported requirements file
+1. On the deployment system,
+    let pip install {{project}} via the exported requirements file
 
     1. Install the dependencies
         ```shell