doctests: switch to the preffered method of calling the tool

which is `cabal repl --with-ghc=doctest`. This not only catches up with
the current upstream recommendations, but also simplifies the usage:
before this change calling doctest required you to set up an environment
with QuickCheck available (we used to do it via cabal-env). The new
method takes care of it automatically.

Also add some docs to fix #8147

.github/workflows/quick-jobs.yml

@@ -65,14 +65,6 @@ jobs:
       - name: Set PATH
         run: |
           echo "$HOME/.cabal/bin" >> $GITHUB_PATH
-      - name: Install cabal-env
-        run: |
-          mkdir -p $HOME/.cabal/bin
-          curl -sL https://github.com/phadej/cabal-extras/releases/download/preview-20191225/cabal-env-snapshot-20191225-x86_64-linux.xz > cabal-env.xz
-          echo "1b567d529c5f627fd8c956e57ae8f0d9f11ee66d6db34b7fb0cb1c370b4edf01  cabal-env.xz" | sha256sum -c -
-          xz -d < cabal-env.xz > $HOME/.cabal/bin/cabal-env
-          rm -f cabal-env.xz
-          chmod a+x $HOME/.cabal/bin/cabal-env
       - uses: actions/cache@v1
         with:
           path: ~/.cabal/store
@@ -91,17 +83,12 @@ jobs:
         run: |
           ghcup --version
           ghcup config set cache true
-          ghcup install ghc recommended
-          ghcup set ghc recommended
+          ghcup install ghc --set recommended
+          ghcup install cabal --set latest
       - name: Update Hackage index
         run: cabal v2-update
-      - name: Install doctest
-        run: cabal v2-install doctest
-      - name: Install libraries
-        run: |
-          cabal-env --transitive QuickCheck
-          cabal-env array bytestring containers deepseq directory filepath pretty process time binary unix text parsec mtl
-          cat $HOME/.ghc/*/environments/default
       - uses: actions/checkout@v3
+      - name: Install doctest
+        run: make doctest-install
       - name: Doctest
         run: make doctest

Makefile

@@ -71,15 +71,27 @@ ghcid-lib :
 ghcid-cli :
 	ghcid -c 'cabal v2-repl cabal-install'
 
-# doctests (relies on .ghc.environment files)
-
+# Artem, 2023-02-03, https://github.com/haskell/cabal/issues/8504
+# The new and prefered way to call the doctest tool (as of now) is based on cabal repl --with-ghc=doctest.
+# The call below reflects the current documentation of the doctest tool except one caveat,
+# which is https://github.com/haskell/cabal/issues/6859, i.e. we have to hide allow-newer in our project
+# file from cabal/doctest. This is easy: we just select a project file with no allow-newer (e.g. cabal.project.libonly).
+#
+# TODO: Cabal-described should be added here but its doctests currently broken, see:
+#       https://github.com/haskell/cabal/issues/8734
+#       Just as well, cabal-install(-solver) doctests (the target below) bitrotted and need some care.
 doctest :
-	doctest --fast -XHaskell2010 Cabal-syntax/src Cabal/src
+	cabal repl --with-ghc=doctest --build-depends=QuickCheck --build-depends=template-haskell --repl-options="-w" --project-file="cabal.project.validate" Cabal-syntax
+	cabal repl --with-ghc=doctest --build-depends=QuickCheck --build-depends=template-haskell --repl-options="-w" --project-file="cabal.project.validate" Cabal
+
 
 # This is not run as part of validate.sh (we need hackage-security, which is tricky to get).
 doctest-cli :
 	doctest -D__DOCTEST__ --fast cabal-install/src cabal-install-solver/src cabal-install-solver/src-assertion
 
+doctest-install:
+	cabal install doctest --overwrite-policy=always --ignore-project
+
 # tests
 
 check-tests :

cabal-testsuite/README.md

@@ -25,6 +25,28 @@ There are a few useful flags:
   the autodetection doesn't work correctly (which may be the
   case for old versions of GHC.)
 
+doctests
+========
+
+You need to install the doctest tool. Make sure it's compiled with your current
+GHC, and don't forget to reinstall it every time you switch GHC version:
+
+``` shellsession
+cabal install doctest --overwrite-policy=always --ignore-project
+```
+
+After that you can run doctests for a component of your choice via the following command:
+
+``` shellsession
+cabal repl --with-ghc=doctest --build-depends=QuickCheck --build-depends=template-haskell --repl-options="-w" --project-file="cabal.project.validate" Cabal-syntax
+```
+
+In this example we have run doctests in `Cabal-syntax`. Notice, that some
+components have broken doctests
+([#8734](https://github.com/haskell/cabal/issues/8734));
+our CI currently checks that `Cabal-syntax` and `Cabal` doctests pass via
+`make doctest-install && make doctest` (you can use this make-based workflow too).
+
 How to write
 ------------