Merge pull request #527 from well-typed/docspec

Use cabal-docspec

Author: phadej

.github/workflows/haskell-ci.yml

@@ -8,9 +8,9 @@
 #
 # For more information, see https://github.com/haskell-CI/haskell-ci
 #
-# version: 0.19.20250710
+# version: 0.19.20250722
 #
-# REGENDATA ("0.19.20250710",["github","--config=cabal.haskell-ci","cabal.project"])
+# REGENDATA ("0.19.20250722",["github","--config=cabal.haskell-ci","cabal.project"])
 #
 name: Haskell-CI
 on:
@@ -172,11 +172,6 @@ jobs:
       - name: update cabal index
         run: |
           $CABAL v2-update -v
-      - name: cache (tools)
-        uses: actions/cache/restore@v4
-        with:
-          key: ${{ runner.os }}-${{ matrix.compiler }}-tools-55831830
-          path: ~/.haskell-ci-tools
       - name: install cabal-plan
         run: |
           mkdir -p $HOME/.cabal/bin
@@ -186,16 +181,15 @@ jobs:
           rm -f cabal-plan.xz
           chmod a+x $HOME/.cabal/bin/cabal-plan
           cabal-plan --version
-      - name: install doctest
+      - name: install cabal-docspec
         run: |
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then $CABAL --store-dir=$HOME/.haskell-ci-tools/store v2-install $ARG_COMPILER --ignore-project -j2 doctest --constraint='doctest ^>=0.22.0' ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest --version ; fi
-      - name: save cache (tools)
-        if: always()
-        uses: actions/cache/save@v4
-        with:
-          key: ${{ runner.os }}-${{ matrix.compiler }}-tools-55831830
-          path: ~/.haskell-ci-tools
+          mkdir -p $HOME/.cabal/bin
+          curl -sL https://github.com/phadej/cabal-extras/releases/download/cabal-docspec-0.0.0.20250606/cabal-docspec-0.0.0.20250606-x86_64-linux.xz > cabal-docspec.xz
+          echo 'cc20bb5c19501b42bde77556bc419c7c0a5c8d1eb65663024d8a4e4c868bef25  cabal-docspec.xz' | sha256sum -c -
+          xz -d < cabal-docspec.xz > $HOME/.cabal/bin/cabal-docspec
+          rm -f cabal-docspec.xz
+          chmod a+x $HOME/.cabal/bin/cabal-docspec
+          cabal-docspec --version
       - name: checkout
         uses: actions/checkout@v4
         with:
@@ -335,24 +329,10 @@ jobs:
       - name: tests
         run: |
           if [ $((! GHCJSARITH)) -ne 0 ] ; then $CABAL v2-test $ARG_COMPILER $ARG_TESTS $ARG_BENCH all --test-show-details=direct ; fi
-      - name: doctest
+      - name: docspec
         run: |
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_optics} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 -XBangPatterns -XConstraintKinds -XDefaultSignatures -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyCase -XFlexibleContexts -XFlexibleInstances -XFunctionalDependencies -XGADTs -XGeneralizedNewtypeDeriving -XInstanceSigs -XKindSignatures -XLambdaCase -XOverloadedLabels -XPatternSynonyms -XRankNTypes -XScopedTypeVariables -XTupleSections -XTypeApplications -XTypeFamilies -XTypeOperators -XViewPatterns src ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_optics_core} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 -XBangPatterns -XConstraintKinds -XDefaultSignatures -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyCase -XFlexibleContexts -XFlexibleInstances -XFunctionalDependencies -XGADTs -XGeneralizedNewtypeDeriving -XInstanceSigs -XKindSignatures -XLambdaCase -XOverloadedLabels -XPatternSynonyms -XRankNTypes -XScopedTypeVariables -XTupleSections -XTypeApplications -XTypeFamilies -XTypeOperators -XViewPatterns src ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_optics_extra} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 -XBangPatterns -XConstraintKinds -XDefaultSignatures -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyCase -XFlexibleContexts -XFlexibleInstances -XFunctionalDependencies -XGADTs -XGeneralizedNewtypeDeriving -XInstanceSigs -XKindSignatures -XLambdaCase -XOverloadedLabels -XPatternSynonyms -XRankNTypes -XScopedTypeVariables -XTupleSections -XTypeApplications -XTypeFamilies -XTypeOperators -XViewPatterns src ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_optics_sop} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 -XBangPatterns -XConstraintKinds -XDefaultSignatures -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyCase -XFlexibleContexts -XFlexibleInstances -XFunctionalDependencies -XGADTs -XGeneralizedNewtypeDeriving -XInstanceSigs -XKindSignatures -XLambdaCase -XOverloadedLabels -XPatternSynonyms -XRankNTypes -XScopedTypeVariables -XTupleSections -XTypeApplications -XTypeFamilies -XTypeOperators -XViewPatterns src ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_optics_th} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 -XBangPatterns -XConstraintKinds -XDefaultSignatures -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyCase -XFlexibleContexts -XFlexibleInstances -XFunctionalDependencies -XGADTs -XGeneralizedNewtypeDeriving -XInstanceSigs -XKindSignatures -XLambdaCase -XOverloadedLabels -XPatternSynonyms -XRankNTypes -XScopedTypeVariables -XTupleSections -XTypeApplications -XTypeFamilies -XTypeOperators -XViewPatterns src ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_optics_vl} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 -XBangPatterns -XConstraintKinds -XDefaultSignatures -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyCase -XFlexibleContexts -XFlexibleInstances -XFunctionalDependencies -XGADTs -XGeneralizedNewtypeDeriving -XInstanceSigs -XKindSignatures -XLambdaCase -XOverloadedLabels -XPatternSynonyms -XRankNTypes -XScopedTypeVariables -XTupleSections -XTypeApplications -XTypeFamilies -XTypeOperators -XViewPatterns src ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_indexed_profunctors} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 -XBangPatterns -XConstraintKinds -XDefaultSignatures -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyCase -XFlexibleContexts -XFlexibleInstances -XFunctionalDependencies -XGADTs -XGeneralizedNewtypeDeriving -XInstanceSigs -XKindSignatures -XLambdaCase -XOverloadedLabels -XPatternSynonyms -XRankNTypes -XScopedTypeVariables -XTupleSections -XTypeApplications -XTypeFamilies -XTypeOperators -XViewPatterns src ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then cd ${PKGDIR_template_haskell_optics} || false ; fi
-          if [ $((! GHCJSARITH && HCNUMVER < 90400)) -ne 0 ] ; then doctest  -XHaskell2010 src ; fi
+          if [ $((! GHCJSARITH && (HCNUMVER < 90400 || HCNUMVER >= 90800))) -ne 0 ] ; then $CABAL v2-build $ARG_COMPILER $ARG_TESTS $ARG_BENCH all ; fi
+          if [ $((! GHCJSARITH && (HCNUMVER < 90400 || HCNUMVER >= 90800))) -ne 0 ] ; then cabal-docspec $ARG_COMPILER ; fi
       - name: cabal check
         run: |
           cd ${PKGDIR_optics} || false

cabal.haskell-ci

@@ -1,9 +1,10 @@
 distribution:   focal
 branches:       master
-doctest:        <9.3
+-- GHC-9.4 and 9.6 have some issue with overlapping instances for optic labels
+docspec:        <9.4 || >=9.8
 tests:          True
 benchmarks:     <9.5
 jobs-selection: any
 
 -- turn head hackage off
-head-hackage: <0
+head-hackage: False

optics-core/optics-core.cabal

@@ -156,3 +156,5 @@ library
                    Optics.Internal.Setter
                    Optics.Internal.Traversal
                    Optics.Internal.Utils
+
+  x-docspec-options: -XTypeApplications -XTypeOperators -XFlexibleContexts -XStandaloneDeriving -XDeriveGeneric -XDataKinds -XOverloadedLabels -XTupleSections

optics-core/src/Data/IntMap/Optics.hs

@@ -50,6 +50,11 @@ import Optics.IxAffineTraversal
 import Optics.IxFold
 import Optics.Optic
 
+-- $setup
+-- >>> import qualified Data.IntMap as IntMap
+-- >>> import Data.Monoid (Sum (..))
+-- >>> import Optics.Core
+
 -- | Construct a map from an 'IxFold'.
 --
 -- The construction is left-biased (see 'IntMap.union'), i.e. the first occurrences of
@@ -132,7 +137,3 @@ ge k = iatraversalVL $ \point f s ->
     Nothing      -> point s
     Just (k', v) -> f k' v <&> \v' -> IntMap.insert k' v' s
 {-# INLINE ge #-}
-
--- $setup
--- >>> import Data.Monoid
--- >>> import Optics.Core

optics-core/src/Data/IntSet/Optics.hs

@@ -17,6 +17,10 @@ import Optics.Fold
 import Optics.Optic
 import Optics.Setter
 
+-- $setup
+-- >>> import qualified Data.IntSet as IntSet
+-- >>> import Optics.Core
+
 -- | IntSet isn't Foldable, but this 'Fold' can be used to access the members of
 -- an 'IntSet'.
 --
@@ -49,6 +53,3 @@ setmapped = sets IntSet.map
 setOf :: Is k A_Fold => Optic' k is s Int -> s -> IntSet
 setOf l = foldMapOf l IntSet.singleton
 {-# INLINE setOf #-}
-
--- $setup
--- >>> import Optics.Core

optics-core/src/Data/Map/Optics.hs

@@ -57,6 +57,11 @@ import Optics.IxAffineTraversal
 import Optics.IxFold
 import Optics.Optic
 
+-- $setup
+-- >>> import qualified Data.Map as Map
+-- >>> import Data.Monoid (Sum (..))
+-- >>> import Optics.Core
+
 -- | Construct a map from an 'IxFold'.
 --
 -- The construction is left-biased (see 'Map.union'), i.e. the first
@@ -139,7 +144,3 @@ ge k = iatraversalVL $ \point f s ->
     Nothing      -> point s
     Just (k', v) -> f k' v <&> \v' -> Map.insert k' v' s
 {-# INLINE ge #-}
-
--- $setup
--- >>> import Data.Monoid
--- >>> import Optics.Core

optics-core/src/Data/Sequence/Optics.hs

@@ -20,6 +20,11 @@ import Optics.IxTraversal
 import Optics.Optic
 import Optics.Traversal
 
+-- $setup
+-- >>> import Data.Sequence (ViewL (..), ViewR (..))
+-- >>> import qualified Data.Sequence as Seq
+-- >>> import Optics.Core
+
 -- * Sequence isomorphisms
 
 -- | A 'Seq' is isomorphic to a 'ViewL'
@@ -136,6 +141,3 @@ sliced i j = conjoined noix ix
 seqOf :: Is k A_Fold => Optic' k is s a -> s -> Seq a
 seqOf l = foldMapOf l Seq.singleton
 {-# INLINE seqOf #-}
-
--- $setup
--- >>> import Optics.Core

optics-core/src/Data/Set/Optics.hs

@@ -16,6 +16,10 @@ import Optics.Fold
 import Optics.Optic
 import Optics.Setter
 
+-- $setup
+-- >>> import qualified Data.Set as Set
+-- >>> import Optics.Core
+
 -- | This 'Setter' can be used to change the type of a 'Set' by mapping the
 -- elements to new values.
 --
@@ -39,6 +43,3 @@ setmapped = sets Set.map
 setOf :: (Is k A_Fold, Ord a) => Optic' k is s a -> s -> Set a
 setOf l = foldMapOf l Set.singleton
 {-# INLINE setOf #-}
-
--- $setup
--- >>> import Optics.Core

optics-core/src/Data/Tree/Optics.hs

@@ -13,6 +13,10 @@ import Data.Tree (Tree (..))
 
 import Optics.Lens
 
+-- $setup
+-- >>> import Data.Tree (Tree (..))
+-- >>> import Optics.Core
+
 -- | A 'Lens' that focuses on the root of a 'Tree'.
 --
 -- >>> view root $ Node 42 []
@@ -27,6 +31,3 @@ root = lensVL $ \f (Node a as) -> (`Node` as) <$> f a
 branches :: Lens' (Tree a) [Tree a]
 branches = lensVL $ \f (Node a as) -> Node a <$> f as
 {-# INLINE branches #-}
-
--- $setup
--- >>> import Optics.Core

optics-core/src/Optics/AffineFold.hs

@@ -60,6 +60,10 @@ import Data.Profunctor.Indexed
 import Optics.Internal.Bi
 import Optics.Internal.Optic
 
+-- $setup
+-- >>> import Data.Maybe (listToMaybe)
+-- >>> import Optics.Core
+
 -- | Type synonym for an affine fold.
 type AffineFold s a = Optic' An_AffineFold NoIx s a
 
@@ -152,6 +156,3 @@ infixl 3 `afailing` -- Same as (<|>)
 isn't :: Is k An_AffineFold => Optic' k is s a -> s -> Bool
 isn't k s = isNothing (preview k s)
 {-# INLINE isn't #-}
-
--- $setup
--- >>> import Optics.Core