From 2658ac6cc52d8fb7c914e685fe694b30b395c485 Mon Sep 17 00:00:00 2001 From: brandon s allbery kf8nh Date: Tue, 21 May 2024 13:12:49 -0400 Subject: [PATCH] generate doc/requirements.txt (#10031) * generate doc/requirements.txt As suggested in https://github.com/haskell/cabal/pull/10030#pullrequestreview-2064505535 * generate doc/requirements.txt As suggested in https://github.com/haskell/cabal/pull/10030#pullrequestreview-2064505535 --- .github/workflows/users-guide.yml | 10 +++- .gitignore | 1 + .readthedocs.yml | 4 ++ doc/README.md | 41 ++++++---------- doc/requirements.txt | 79 ------------------------------- 5 files changed, 27 insertions(+), 108 deletions(-) delete mode 100644 doc/requirements.txt diff --git a/.github/workflows/users-guide.yml b/.github/workflows/users-guide.yml index 8047ede1031..8442b39c2f4 100644 --- a/.github/workflows/users-guide.yml +++ b/.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: | diff --git a/.gitignore b/.gitignore index 3e0b65c8085..97632785e28 100644 --- a/.gitignore +++ b/.gitignore @@ -87,6 +87,7 @@ cabal-testsuite/**/haddocks venv .venv /doc/.skjold_cache/ +/doc/requirements.txt # macOS folder metadata .DS_Store diff --git a/.readthedocs.yml b/.readthedocs.yml index 016f7e47a48..31bb9507b4f 100644 --- a/.readthedocs.yml +++ b/.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: diff --git a/doc/README.md b/doc/README.md index c3b25787ce6..871ae85d068 100644 --- a/doc/README.md +++ b/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 diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index 1f2df5538b7..00000000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,79 +0,0 @@ -# -# This file is autogenerated by pip-compile with Python 3.11 -# by the following command: -# -# pip-compile requirements.in -# -alabaster==0.7.13 - # via sphinx -babel==2.12.1 - # via sphinx -certifi==2023.7.22 - # via - # -r requirements.in - # requests -charset-normalizer==3.1.0 - # via requests -docutils==0.18.1 - # via - # sphinx - # sphinx-jsonschema - # sphinx-rtd-theme -idna==3.7 - # via - # -r requirements.in - # requests -imagesize==1.4.1 - # via sphinx -jinja2==3.1.4 - # via - # -r requirements.in - # sphinx -jsonpointer==2.3 - # via sphinx-jsonschema -markupsafe==2.1.2 - # via jinja2 -packaging==23.1 - # via sphinx -pygments==2.15.1 - # via - # -r requirements.in - # sphinx -pyyaml==6.0 - # via sphinx-jsonschema -requests==2.31.0 - # via - # sphinx - # sphinx-jsonschema -snowballstemmer==2.2.0 - # via sphinx -sphinx==5.3.0 - # via - # -r requirements.in - # sphinx-rtd-theme - # sphinxcontrib-jquery - # sphinxnotes-strike -sphinx-jsonschema==1.19.1 - # via -r requirements.in -sphinx-rtd-theme==1.2.1 - # via -r requirements.in -sphinxcontrib-applehelp==1.0.4 - # via sphinx -sphinxcontrib-devhelp==1.0.2 - # via sphinx -sphinxcontrib-htmlhelp==2.0.1 - # via sphinx -sphinxcontrib-jquery==4.1 - # via sphinx-rtd-theme -sphinxcontrib-jsmath==1.0.1 - # via sphinx -sphinxcontrib-qthelp==1.0.3 - # via sphinx -sphinxcontrib-serializinghtml==1.1.5 - # via sphinx -sphinxnotes-strike==1.2 - # via -r requirements.in -urllib3==2.0.7 - # via - # -r requirements.in - # requests