Merge pull request #8812 from haskell/mergify/bp/3.10/pr-8789

Doc: bump to Python 3.10; Sphinx 5.3.0. Remove `--constraint: foo -none` & some polishing (backport #8789)

.github/workflows/users-guide.yml

@@ -46,7 +46,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.7]
+        python-version: ['3.10']
 
     steps:
     - uses: actions/checkout@v3

doc/Makefile

@@ -23,6 +23,7 @@ build-and-check-requirements: requirements.txt check-requirements
 # See https://modelpredict.com/wht-requirements-txt-is-not-enough
 requirements.txt: requirements.in
 	. ../.python-sphinx-virtualenv/bin/activate \
+	  && pip install --upgrade pip \
 	  && pip install pip-tools \
 	  && pip-compile requirements.in
 

doc/requirements.in

@@ -1,6 +1,8 @@
-sphinx >= 5
-sphinx_rtd_theme >= 1
+sphinx == 5.3.0
+sphinx_rtd_theme >= 1.2
 sphinx-jsonschema
 sphinxnotes-strike
 # Pygments>=2.7.4 suggested by CVE-2021-20270 CVE-2021-27291
 Pygments >= 2.7.4
+# Suggested by dependabot in https://github.com/haskell/cabal/pull/8807
+certifi >= 2022.12.7

doc/requirements.txt

@@ -1,42 +1,40 @@
 #
-# This file is autogenerated by pip-compile with python 3.9
-# To update, run:
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
 #
 #    pip-compile requirements.in
 #
 alabaster==0.7.12
     # via sphinx
 babel==2.9.1
     # via sphinx
-certifi==2021.10.8
-    # via requests
+certifi==2022.12.7
+    # via
+    #   -r requirements.in
+    #   requests
 charset-normalizer==2.0.7
     # via requests
-docutils==0.17.1
+docutils==0.18.1
     # via
     #   sphinx
     #   sphinx-jsonschema
     #   sphinx-rtd-theme
 idna==2.10
     # via requests
-imagesize==1.2.0
-    # via sphinx
-importlib-metadata==4.11.4
+imagesize==1.4.1
     # via sphinx
-jinja2==2.11.3
+jinja2==3.1.2
     # via sphinx
 jsonpointer==2.1
     # via sphinx-jsonschema
-markupsafe==1.1.1
+markupsafe==2.1.2
     # via jinja2
-packaging==20.9
+packaging==23.0
     # via sphinx
-pygments==2.10.0
+pygments==2.14.0
     # via
     #   -r requirements.in
     #   sphinx
-pyparsing==2.4.7
-    # via packaging
 pytz==2021.3
     # via babel
 pyyaml==5.4.1
@@ -47,21 +45,23 @@ requests==2.26.0
     #   sphinx-jsonschema
 snowballstemmer==2.1.0
     # via sphinx
-sphinx==5.0.1
+sphinx==5.3.0
     # via
     #   -r requirements.in
     #   sphinx-rtd-theme
     #   sphinxnotes-strike
 sphinx-jsonschema==1.16.11
     # via -r requirements.in
-sphinx-rtd-theme==1.0.0
+sphinx-rtd-theme==1.2.0
     # via -r requirements.in
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.0
     # via sphinx
+sphinxcontrib-jquery==2.0.0
+    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.3
@@ -72,5 +72,6 @@ sphinxnotes-strike==1.1
     # via -r requirements.in
 urllib3==1.26.7
     # via requests
-zipp==3.8.0
-    # via importlib-metadata
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

doc/setup-commands.rst

@@ -880,37 +880,29 @@ Miscellaneous options
 .. option:: --constraint=constraint
 
     Restrict solutions involving a package to given version
-    bounds, flag settings, and other properties. For example, to
-    consider only install plans that use version 2.1 of ``bar``
-    or do not use ``bar`` at all, write:
+    bounds, flag settings, and other properties.
+
+    The following considers only install plans where ``bar``,
+    if used, is restricted to version 2.1:
 
     ::
 
         $ cabal install --constraint="bar == 2.1"
 
-    Version bounds have the same syntax as :pkg-field:`build-depends`.
-    As a special case, the following prevents ``bar`` from being
-    used at all:
+    The following prevents ``bar`` from being used at all:
 
     ::
 
-        # Note: this is just syntax sugar for '> 1 && < 1', and is
-        # supported by build-depends.
-        $ cabal install --constraint="bar -none"
-
-    You can also specify flag assignments:
+        $ cabal install --constraint="bar <0"
 
-    ::
-
-        # Require bar to be installed with the foo flag turned on and
-        # the baz flag turned off.
-        $ cabal install --constraint="bar +foo -baz"
+    Version bounds have the same syntax as :pkg-field:`build-depends`.
+    Yet extra pseudo version bounds are available here in addition:
 
-    To specify multiple constraints, you may pass the
-    ``constraint`` option multiple times.
+      - ``installed`` to fix a package to the already installed version.
+        Often useful for GHC-supplied packages in combination with :cfg-field:`allow-newer`,
+        e.g., ``--allow-newer='*:base' --constraint='base installed'``.
 
-    There are also some more specialized constraints, which most people
-    don't generally need:
+      - ``source`` to fix a package to the local source copy.
 
     ::
 
@@ -924,18 +916,30 @@ Miscellaneous options
         # specify this.)
         $ cabal install --constraint="bar source"
 
+    Further, we can specify flag assignments with ``+FLAG`` and ``-FLAG``
+    or enable test (``test``) and benchmark (``bench``) suites:
+
+    ::
+
+        # Require bar to be installed with the foo flag turned on and
+        # the baz flag turned off.
+        $ cabal install --constraint="bar +foo -baz"
+
         # Require that bar have test suites and benchmarks enabled.
         $ cabal install --constraint="bar test" --constraint="bar bench"
 
+    To specify multiple constraints, you may pass the
+    ``constraint`` option multiple times.
+
     By default, constraints only apply to build dependencies
     (:pkg-field:`build-depends`), build dependencies of build
     dependencies, and so on. Constraints normally do not apply to
     dependencies of the ``Setup.hs`` script of any package
     (:pkg-field:`custom-setup:setup-depends`) nor do they apply to build tools
     (:pkg-field:`build-tool-depends`) or the dependencies of build
     tools. To explicitly apply a constraint to a setup or build
-    tool dependency, you can add a qualifier to the constraint as
-    follows:
+    tool dependency, you can add a qualifier ``setup`` or ``any``
+    to the constraint as follows:
 
     ::