Merge pull request #6513 from commercialhaskell/re729

Re #729 Add `--haddock-tests` and `--haddock-benchmarks`

.stan.toml

@@ -190,25 +190,25 @@
 
 # Anti-pattern: unsafe functions
 [[ignore]]
-  id = "OBS-STAN-0212-FNS1cF-57:17"
+  id = "OBS-STAN-0212-FNS1cF-59:17"
 # ✦ Description:   Usage of unsafe functions breaks referential transparency
 # ✦ Category:      #Unsafe #AntiPattern
 # ✦ File:          src\Stack\BuildOpts.hs
 #
-#   56 ┃
-#   57 ┃   buildMonoid = undefined :: BuildOptsMonoid
-#   58 ┃                 ^^^^^^^^^
+#   58 ┃
+#   59 ┃   buildMonoid = undefined :: BuildOptsMonoid
+#   60 ┃                 ^^^^^^^^^
 
 # Anti-pattern: unsafe functions
 [[ignore]]
-  id = "OBS-STAN-0212-FNS1cF-69:14"
+  id = "OBS-STAN-0212-FNS1cF-71:14"
 # ✦ Description:   Usage of unsafe functions breaks referential transparency
 # ✦ Category:      #Unsafe #AntiPattern
 # ✦ File:          src\Stack\BuildOpts.hs
 #
-#    68 ┃
-#    69 ┃   toMonoid = undefined :: TestOptsMonoid
-#    70 ┃              ^^^^^^^^^
+#    70 ┃
+#    71 ┃   toMonoid = undefined :: TestOptsMonoid
+#    72 ┃              ^^^^^^^^^
 
 # Anti-pattern: Pattern matching on '_'
 # Pattern matching on '_' for sum types can create maintainability issues

ChangeLog.md

@@ -28,10 +28,12 @@ Other enhancements:
 * In YAML configuration files, the `default-init-snapshot` key is introduced to
   allow a default snapshot to be specified for use with the `stack init`
   command, as if it had been specified at the command line.
-* Add flag `--haddock-executables` to Stack's `build` command (including the
-  `haddock` synonym for `build --haddock`) to enable also building Haddock
-  documentation for executables. Due to a bug in Cabal (the library), Stack will
-  ignore the flag with a warning for GHC versions before 9.4.
+* Add flags `--haddock-executables`, `--haddock-tests` and
+  `--haddock-benchmarks` to Stack's `build` command (including the `haddock`
+  synonym for `build --haddock`) to enable also building Haddock
+  documentation for executables, test suites and benchmarks. Due to a bug in
+  Cabal (the library), Stack will ignore the flags with a warning for GHC
+  versions before 9.4.
 
 Bug fixes:
 

doc/build_command.md

@@ -319,6 +319,23 @@ Unset the flag to disable building building hyperlinked source for Haddock.
 If the [`--haddock-for-hackage`](#-no-haddock-for-haddock-flag) flag is passed,
 this flag is ignored.
 
+### `--[no-]haddock-benchmarks` flag
+
+Default: Disabled
+
+Set the flag to enable building Haddock documentation for benchmark components
+of packages.
+
+If the [`--haddock-for-hackage`](#-no-haddock-for-haddock-flag) flag is passed,
+this flag is ignored.
+
+!!! warning
+
+    Due to a bug, if there is more than one executable (including test suites
+    and benchmarks) in a project package or more than one project package with
+    an executable, the Haddock documentation for the `Main` module of one
+    executable will overwrite the Haddock documentation for others.
+
 ### `--[no-]haddock-executables` flag
 
 Default: Disabled
@@ -331,10 +348,10 @@ this flag is ignored.
 
 !!! warning
 
-    Due to a bug, if there is more than one executable in a project package or
-    more than one project package with an executable, the Haddock documentation
-    for the `Main` module of one executable will overwrite the Haddock
-    documentation for others.
+    Due to a bug, if there is more than one executable (including test suites
+    and benchmarks) in a project package or more than one project package with
+    an executable, the Haddock documentation for the `Main` module of one
+    executable will overwrite the Haddock documentation for others.
 
 ### `--[no-]haddock-internal` flag
 
@@ -345,6 +362,23 @@ Set the flag to enable building Haddock documentation for internal modules.
 If the [`--haddock-for-hackage`](#-no-haddock-for-haddock-flag) flag is passed,
 this flag is ignored.
 
+### `--[no-]haddock-tests` flag
+
+Default: Disabled
+
+Set the flag to enable building Haddock documentation for test suite components
+of packages.
+
+If the [`--haddock-for-hackage`](#-no-haddock-for-haddock-flag) flag is passed,
+this flag is ignored.
+
+!!! warning
+
+    Due to a bug, if there is more than one executable (including test suites
+    and benchmarks) in a project package or more than one project package with
+    an executable, the Haddock documentation for the `Main` module of one
+    executable will overwrite the Haddock documentation for others.
+
 ### `--[no-]keep-going` flag
 
 Default (`stack build`): Disabled

src/Stack/Build.hs

@@ -194,12 +194,17 @@ build msetLocalFiles = do
       localsIdents -> throwM $ LocalPackagesPresent localsIdents
 
     checkCabalVersion
-    haddockExecutablesSupported <- warnAboutHaddockExecutables bopts
-    let disableHaddockExecutables =
-          local $ over buildOptsL $ \bo -> bo { haddockExecutables = False }
-        withHaddockExecutablesGuarded = if haddockExecutablesSupported
+    haddockCompsSupported <- warnAboutHaddockComps bopts
+    let disableHaddockComps =
+          local $ over buildOptsL $ \bo ->
+            bo
+              { haddockExecutables = False
+              , haddockTests = False
+              , haddockBenchmarks = False
+              }
+        withHaddockCompsGuarded = if haddockCompsSupported
           then id
-          else disableHaddockExecutables
+          else disableHaddockComps
     warnAboutSplitObjs bopts
     warnIfExecutablesWithSameNameCouldBeOverwritten locals plan
 
@@ -210,7 +215,7 @@ build msetLocalFiles = do
       then
         printPlan plan
       else
-        withHaddockExecutablesGuarded $ executePlan
+        withHaddockCompsGuarded $ executePlan
           boptsCli
           baseConfigOpts
           locals
@@ -325,32 +330,35 @@ warnIfExecutablesWithSameNameCouldBeOverwritten locals plan = do
   collect :: Ord k => [(k, v)] -> Map k (NonEmpty v)
   collect = Map.mapMaybe nonEmpty . Map.fromDistinctAscList . groupSort
 
-warnAboutHaddockExecutables ::
+warnAboutHaddockComps ::
      (HasCompiler env, HasTerm env)
   => BuildOpts
   -> RIO env Bool
-warnAboutHaddockExecutables bopts = do
+warnAboutHaddockComps bopts = do
+  let haddockCompsWanted =
+           bopts.haddockExecutables
+        || bopts.haddockTests
+        || bopts.haddockBenchmarks
   cabalVer <- view cabalVersionL
-  if cabalVer < mkVersion [3, 8, 1]
+  if haddockCompsWanted && cabalVer < mkVersion [3, 8, 1]
     then do
       prettyWarnL
         [ flow "Stack builds Haddock documentation with the version of the \
                \Cabal package that comes with the specified version of GHC. \
                \Version"
         , fromString $ versionString cabalVer
         , flow "was found, which does not support the building of \
-               \documentation for executables. The option to build such \
-               \documentation will be ignored. To use the option, use a \
-               \snapshot that specifies a version of GHC that is 9.4 or later. \
-               \Stackage LTS Haskell 21.0"
+               \documentation for executables, test suites or benchmarks. \
+               \Options to build such documentation will be ignored. To use \
+               \the options, use a snapshot that specifies a version of GHC \
+               \that is 9.4 or later. Stackage LTS Haskell 21.0"
         , parens (style Shell "lts-21.0")
         , flow "or later or Nightly 2022-11-19"
         , parens (style Shell "nightly-2022-11-19")
         , flow "or later specify such GHC versions."
         ]
       pure False
-    else
-      pure bopts.haddockExecutables
+    else pure haddockCompsWanted
 
 warnAboutSplitObjs :: HasTerm env => BuildOpts -> RIO env ()
 warnAboutSplitObjs bopts |  bopts.splitObjs =

src/Stack/Build/ExecutePackage.hs

@@ -610,6 +610,8 @@ realConfigAndBuild
                         | ee.buildOpts.haddockHyperlinkSource
                         ]
                       , [ "--executables" | ee.buildOpts.haddockExecutables ]
+                      , [ "--tests" | ee.buildOpts.haddockTests ]
+                      , [ "--benchmarks" | ee.buildOpts.haddockBenchmarks ]
                       , [ "--internal" | ee.buildOpts.haddockInternal  ]
                       , quickjump
                       ]

src/Stack/BuildOpts.hs

@@ -32,6 +32,8 @@ defaultBuildOpts = BuildOpts
   , openHaddocks = defaultFirstFalse buildMonoid.openHaddocks
   , haddockDeps = Nothing
   , haddockExecutables = defaultFirstFalse buildMonoid.haddockExecutables
+  , haddockTests = defaultFirstFalse buildMonoid.haddockTests
+  , haddockBenchmarks = defaultFirstFalse buildMonoid.haddockBenchmarks
   , haddockInternal = defaultFirstFalse buildMonoid.haddockInternal
   , haddockHyperlinkSource = defaultFirstTrue buildMonoid.haddockHyperlinkSource
   , haddockForHackage = defaultFirstFalse buildMonoid.haddockForHackage

src/Stack/Config/Build.hs

@@ -57,6 +57,12 @@ buildOptsFromMonoid buildMonoid = BuildOpts
   , haddockExecutables =
          not isHaddockFromHackage
       && fromFirstFalse buildMonoid.haddockExecutables
+  , haddockTests =
+         not isHaddockFromHackage
+      && fromFirstFalse buildMonoid.haddockTests
+  , haddockBenchmarks =
+         not isHaddockFromHackage
+      && fromFirstFalse buildMonoid.haddockBenchmarks
   , haddockInternal =
          not isHaddockFromHackage
       && fromFirstFalse buildMonoid.haddockInternal

src/Stack/Options/BuildMonoidParser.hs

@@ -42,6 +42,8 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid
   <*> openHaddocks
   <*> haddockDeps
   <*> haddockExecutables
+  <*> haddockTests
+  <*> haddockBenchmarks
   <*> haddockInternal
   <*> haddockHyperlinkSource
   <*> haddockForHackage
@@ -139,6 +141,16 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid
     "also building Haddock documentation for all executables (like \
     \'cabal haddock --executables')."
     hide
+  haddockTests = firstBoolFlagsFalse
+    "haddock-tests"
+    "also building Haddock documentation for all test suites (like \
+    \'cabal haddock --tests')."
+    hide
+  haddockBenchmarks = firstBoolFlagsFalse
+    "haddock-benchmarks"
+    "also building Haddock documentation for all benchmarks (like \
+    \'cabal haddock --benchmarks')."
+    hide
   haddockInternal = firstBoolFlagsFalse
     "haddock-internal"
     "building Haddock documentation for internal modules (like \

src/Stack/Types/BuildOpts.hs

@@ -35,6 +35,12 @@ data BuildOpts = BuildOpts
   , haddockExecutables :: !Bool
     -- ^ Also build Haddock documentation for all executable components, like
     -- @runghc Setup.hs haddock --executables@.
+  , haddockTests :: !Bool
+    -- ^ Also build Haddock documentation for all test suite components, like
+    -- @runghc Setup.hs haddock --tests@.
+  , haddockBenchmarks :: !Bool
+    -- ^ Also build Haddock documentation for all benchmark components, like
+    -- @runghc Setup.hs haddock --benchmarks@.
   , haddockInternal :: !Bool
     -- ^ Build haddocks for all symbols and packages, like
     -- @cabal haddock --internal@

src/Stack/Types/BuildOptsMonoid.hs

@@ -46,6 +46,8 @@ data BuildOptsMonoid = BuildOptsMonoid
   , openHaddocks :: !FirstFalse
   , haddockDeps :: !(First Bool)
   , haddockExecutables :: !FirstFalse
+  , haddockTests :: !FirstFalse
+  , haddockBenchmarks :: !FirstFalse
   , haddockInternal :: !FirstFalse
   , haddockHyperlinkSource :: !FirstTrue
   , haddockForHackage :: !FirstFalse
@@ -83,6 +85,8 @@ instance FromJSON (WithJSONWarnings BuildOptsMonoid) where
     openHaddocks <- FirstFalse <$> o ..:? openHaddocksArgName
     haddockDeps <- First <$> o ..:? haddockDepsArgName
     haddockExecutables <- FirstFalse <$> o ..:? haddockExecutablesArgName
+    haddockTests <- FirstFalse <$> o ..:? haddockTestsArgName
+    haddockBenchmarks <- FirstFalse <$> o ..:? haddockBenchmarksArgName
     haddockInternal <- FirstFalse <$> o ..:? haddockInternalArgName
     haddockHyperlinkSource <- FirstTrue <$> o ..:? haddockHyperlinkSourceArgName
     haddockForHackage <-  FirstFalse <$> o ..:? haddockForHackageArgName
@@ -118,6 +122,8 @@ instance FromJSON (WithJSONWarnings BuildOptsMonoid) where
       , openHaddocks
       , haddockDeps
       , haddockExecutables
+      , haddockTests
+      , haddockBenchmarks
       , haddockInternal
       , haddockHyperlinkSource
       , haddockForHackage
@@ -167,6 +173,12 @@ haddockDepsArgName = "haddock-deps"
 haddockExecutablesArgName :: Text
 haddockExecutablesArgName = "haddock-executables"
 
+haddockTestsArgName :: Text
+haddockTestsArgName = "haddock-tests"
+
+haddockBenchmarksArgName :: Text
+haddockBenchmarksArgName = "haddock-benchmarks"
+
 haddockInternalArgName :: Text
 haddockInternalArgName = "haddock-internal"
 

tests/unit/Stack/ConfigSpec.hs

@@ -72,6 +72,8 @@ buildOptsConfig =
   "  open-haddocks: true\n" ++
   "  haddock-deps: true\n" ++
   "  haddock-executables: true\n" ++
+  "  haddock-tests: true\n" ++
+  "  haddock-benchmarks: true\n" ++
   "  haddock-internal: true\n" ++
   "  haddock-hyperlink-source: false\n" ++
   "  haddock-for-hackage: false\n" ++
@@ -109,6 +111,8 @@ buildOptsHaddockForHackageConfig =
   "  open-haddocks: true\n" ++
   "  haddock-deps: true\n" ++
   "  haddock-executables: true\n" ++
+  "  haddock-tests: true\n" ++
+  "  haddock-benchmarks: true\n" ++
   "  haddock-internal: true\n" ++
   "  haddock-hyperlink-source: false\n" ++
   "  haddock-for-hackage: true\n" ++
@@ -235,6 +239,8 @@ spec = beforeAll setup $ do
         bopts.openHaddocks `shouldBe` True
         bopts.haddockDeps `shouldBe` Just True
         bopts.haddockExecutables `shouldBe` True
+        bopts.haddockTests `shouldBe` True
+        bopts.haddockBenchmarks `shouldBe` True
         bopts.haddockInternal `shouldBe` True
         bopts.haddockHyperlinkSource `shouldBe` False
         bopts.haddockForHackage `shouldBe` False