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

Author: ulysses4ever

.github/workflows/quick-jobs.yml

@@ -54,14 +54,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
@@ -70,16 +62,11 @@ jobs:
         run: |
           ghcup config set cache true
           ghcup install ghc recommended
-          ghcup set ghc recommended
+          ghcup install cabal 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: Doctest
         run: make doctest

Makefile

@@ -71,10 +71,18 @@ 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
+
 
 # This is not run as part of validate.sh (we need hackage-security, which is tricky to get).
 doctest-cli :

cabal-testsuite/README.md

@@ -25,6 +25,26 @@ 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:
+
+``` 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 Cabal
+```
+
+In this example we run doctests in `Cabal-syntax` and `Cabal`. Exactly the same
+can be done via `make doctest` (that's what our CI does). Notice, that some
+components have broken doctests ([#8734](https://github.com/haskell/cabal/issues/8734)).
+
 How to write
 ------------