generate doc/requirements.txt (#10031)

* generate doc/requirements.txt

As suggested in #10030 (review)

* generate doc/requirements.txt

As suggested in #10030 (review)

.github/workflows/users-guide.yml

@@ -15,7 +15,6 @@ on:
     - 'doc/Makefile'
     - 'doc/pyproject.toml'
     - 'doc/requirements.in'
-    - 'doc/requirements.txt'
     - 'doc/*.inc'
     - 'doc/*.py'
     - 'doc/*.rst'
@@ -26,7 +25,6 @@ on:
     - 'doc/Makefile'
     - 'doc/pyproject.toml'
     - 'doc/requirements.in'
-    - 'doc/requirements.txt'
     - 'doc/*.inc'
     - 'doc/*.py'
     - 'doc/*.rst'
@@ -58,6 +56,14 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
+    - name: Install pip-compile
+      run: |
+        pip install pip-tools
+
+    - name: Create requirements.txt from requirements.in
+      run: |
+        make users-guide-requirements
+
     # Subsumed by make users-guide
     # - name: Install dependencies
     #   run: |

.gitignore

@@ -87,6 +87,7 @@ cabal-testsuite/**/haddocks
 venv
 .venv
 /doc/.skjold_cache/
+/doc/requirements.txt
 
 # macOS folder metadata
 .DS_Store

.readthedocs.yml

@@ -7,6 +7,10 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.8"
+  jobs:
+    post_create_environment:
+      - pip install pip-tools
+      - make users-guide-requirements
 
 python:
   install:

doc/README.md

@@ -11,48 +11,34 @@ http://cabal.readthedocs.io/
 
 ### How to build it
 
-Building the documentation requires Python 3 and PIP. Run the following command either from the root of the cabal repository or from the `docs/` subdirectory:
+Building the documentation requires Python 3, PIP, and `pip-tools` (see the second note below for how to install it). Run the following command either from the root of the cabal repository or from the `docs/` subdirectory:
 
 ``` console
-make users-guide
+> make users-guide
 ```
 
 Note: Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, so unset the variable
 and instead set `LC_ALL=en_US.UTF-8`.
 
-### How to update dependencies
-
-Once in a while you need to update Python dependencies (for instance,
-when Dependabot alerts about possible security flaw). The list of
-transitive dependencies (`requirements.txt`) is generated from the
-list of direct dependencies in `requirements.in`. To perform the
-generation step run
+Note: You can use a vendor package for `pip-tools`, or run
 
-```console
-> make users-guide-requirements
+``` console
+> pip install pip-tools
 ```
 
-either from the root of the cabal repository or from the `docs/` subdirectory.
+Make sure the installation directory (often `$HOME/.local/bin`) is on your `$PATH`.
 
-Note that generating `requirements.txt` is sensitive to the Python version.
-The version currently used is stamped at the top of `requirements.txt`.
-Normally, we would expect the same version of Python to be used for
-regeneration. An easy way to enforce a particular version is to perform
-regeneration in a Docker container, e.g. (from the root of repository):
+### How to update dependencies
+
+The list of transitive dependencies (`requirements.txt`) is generated from the list of direct dependencies in `requirements.in`. To perform the generation step, run
 
 ```console
-> docker run -itv $PWD:/cabal python:3.10-alpine sh
-...
-# apk add make
-...
-# cd cabal
-# make users-guide-requirements
+> make users-guide-requirements
 ```
 
-One way to make sure the dependencies are reasonably up to date
-is to remove `requirements.txt` and regenerate it as described
-above. But in some cases you may have to add a bound manually
-to `requirements.in`, e.g. `requests >= 2.31.0`.
+either from the root of the cabal repository or from the `docs/` subdirectory. You will need to do this before building documentation the first time, but should only need to repeat it after a `git clean` or if the dependencies in `requirements.in` change.
+
+In some cases, you may have to add a bound manually to `requirements.in`, e.g. `requests >= 2.31.0`.
 
 ### Gitpod workflow
 
@@ -70,6 +56,7 @@ Make your edits, rebuild the guide and refresh the browser to preview the
 changes. When happy, commit your changes with git in the included terminal.
 
 ### Caveats, for newcomers to RST from MD
+
 RST does not allow you to skip section levels when nesting, like MD
 does.
 So, you cannot have