Merge pull request #6282 from commercialhaskell/re6270-1

Re #6270 Step 1, provide `--haddock-for-hackage`
commercialhaskell · Oct 8, 2023 · 72bb687 · 72bb687
2 parents d5d49f0 + d9139af
commit 72bb687
Show file tree

Hide file tree

Showing 8 changed files with 107 additions and 37 deletions.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -31,6 +31,9 @@ Other enhancements:
 * Add option of the form `--doctest-option=<argument>` to `stack build`, where
   `doctest` is a program recognised by versions of the Cabal library from
   `1.24.0.0`.
+* Experimental: Add flag `--haddock-for-hackage` to Stack's `build` command
+  (including the `haddock` synonym for `build --haddock`) to enable building
+  with flags to generate Haddock documentation suitable for upload to Hackage.
 
 Bug fixes:
 
@@ -231,8 +234,8 @@ Other enhancements:
   `STACK_ROOT` environment variable.
 * Add `stack path --global-config`, to yield the full path of Stack's
   user-specific global YAML configuration file (`config.yaml`).
-* Add an experimental option, `allow-newer-deps`, which allows users to
-  specify a subset of dependencies for which version bounds should be ignored
+* Experimental: Add option `allow-newer-deps`, which allows users to specify a
+  subset of dependencies for which version bounds should be ignored
   (`allow-newer-deps: ['foo', 'bar']`). This field has no effect unless
   `allow-newer` is enabled.
 
@@ -784,7 +787,7 @@ Major changes:
 * Remove the `stack image` command. With the advent of Docker multistage
   builds, this functionality is no longer useful. For an example, please see
   [Building Haskell Apps with Docker](https://www.fpcomplete.com/blog/2017/12/building-haskell-apps-with-docker).
-* Support building GHC from source (experimental)
+* Experimental: Support building GHC from source
     * Stack now supports building and installing GHC from source. The built GHC
       is uniquely identified by a commit id and an Hadrian "flavour" (Hadrian is
       the newer GHC build system), hence `compiler` can be set to use a GHC
@@ -1667,11 +1670,10 @@ Other enhancements:
   [#3126](https://github.com/commercialhaskell/stack/issues/3126)
 * When using Nix, nix-shell now depends always on git to prevent runtime errors
   while fetching metadata
-* The `stack unpack` command now accepts a form where an explicit
-  Hackage revision hash is specified, e.g. `stack unpack
-  foo-1.2.3@gitsha1:deadbeef`. Note that this should be considered
-  _experimental_, Stack will likely move towards a different hash
-  format in the future.
+* Experimental: The `stack unpack` command now accepts a form where an explicit
+  Hackage revision hash is specified, e.g.
+  `stack unpack foo-1.2.3@gitsha1:deadbeef`. Note that Stack will likely move
+  towards a different hash format in the future.
 * Binary "stack upgrade" will now warn if the installed executable is not
   on the PATH or shadowed by another entry.
 * Allow running tests on tarball created by sdist and upload
@@ -2286,7 +2288,7 @@ Other enhancements:
 * Fix too much rebuilding when enabling/disabling profiling flags.
 * `stack build pkg-1.0` will now build `pkg-1.0` even if the snapshot specifies
   a different version (it introduces a temporary extra-dep)
-* Experimental support for `--split-objs` added
+* Experimental: Support for `--split-objs` added
   [#1284](https://github.com/commercialhaskell/stack/issues/1284).
 * `git` packages with submodules are supported by passing the `--recursive`
   flag to `git clone`.
@@ -2765,7 +2767,7 @@ Other enhancements:
   [#1070](https://github.com/commercialhaskell/stack/pull/1070)
 * Use Stack-installed GHCs for `stack init --solver`
   [#1072](https://github.com/commercialhaskell/stack/issues/1072)
-* New experimental `stack query` command
+* Experimental: Add `stack query` command
   [#1087](https://github.com/commercialhaskell/stack/issues/1087)
 * By default, Stack no longer rebuilds a package due to GHC options changes.
   This behavior can be tweaked with the `rebuild-ghc-options` setting.

diff --git a/doc/build_command.md b/doc/build_command.md
@@ -12,11 +12,11 @@ stack build [TARGET] [--dry-run] [--pedantic] [--fast] [--ghc-options OPTIONS]
             [--[no-]library-stripping] [--[no-]executable-stripping]
             [--[no-]haddock] [--haddock-arguments HADDOCK_ARGS]
             [--[no-]open] [--[no-]haddock-deps] [--[no-]haddock-internal]
-            [--[no-]haddock-hyperlink-source] [--[no-]copy-bins]
-            [--[no-]copy-compiler-tool] [--[no-]prefetch] [--[no-]keep-going]
-            [--[no-]keep-tmp-files] [--[no-]force-dirty] [--[no-]test]
-            [--[no-]rerun-tests] [--ta|--test-arguments TEST_ARGS] [--coverage]
-            [--no-run-tests] [--test-suite-timeout ARG]
+            [--[no-]haddock-hyperlink-source] [--[no-]haddock-for-hackage]
+            [--[no-]copy-bins] [--[no-]copy-compiler-tool] [--[no-]prefetch]
+            [--[no-]keep-going] [--[no-]keep-tmp-files] [--[no-]force-dirty]
+            [--[no-]test] [--[no-]rerun-tests] [--ta|--test-arguments TEST_ARGS]
+            [--coverage] [--no-run-tests] [--test-suite-timeout ARG]
             [--[no-]tests-allow-stdin] [--[no-]bench]
             [--ba|--benchmark-arguments BENCH_ARGS] [--no-run-benchmarks]
             [--[no-]reconfigure] [--cabal-verbosity VERBOSITY |
@@ -234,18 +234,58 @@ Default: Enabled (if building Haddock documnentation)
 
 Unset the flag to disable building Haddock documentation for dependencies.
 
+### `--[no-]haddock-for-haddock` flag
+
+:octicons-beaker-24: Experimental
+
+:octicons-tag-24: UNRELEASED
+
+Default: Disabled
+
+Set the flag to build with flags to generate Haddock documentation suitable for
+upload to Hackage.
+
+For each local package, the generated Haddock documentation files are in
+directory `doc\html\<package_version>-docs\`, relative to Stack's dist work
+directory (see `stack path --dist-dir`).
+
+If the flag is set:
+
+* the [`--[no-]haddock-hyperlink-source`](#no-haddock-hyperlink-source-flag)
+  flag is ignored and `--haddock-hyperlink-source` is implied; and
+* the [`--[no-]haddock-internal`](#no-haddock-hyperlink-internal-flag) flag is
+  ignored and `--no-haddock-internal` is implied.
+
+!!! note
+
+    If set, Haddock will warn that `-source-*` options are ignored when
+    `--hyperlinked-source` is enabled. That is due to a known bug in Cabal
+    (the libiary).
+
+!!! note
+
+    If set, Cabal (the library) will report that documentation has been created
+    in `index.html` and `<package_name>.txt` files. Those files do not exist.
+    That false report is due to a known bug in Cabal (the library).
+
 ### `--[no-]haddock-hyperlink-source` flag
 
 Default: Enabled
 
 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-internal` flag
 
 Default: Disabled
 
 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-]keep-going` flag
 
 Default (`stack build`): Disabled

diff --git a/doc/path_command.md b/doc/path_command.md
@@ -23,7 +23,7 @@ Pass the following flags for information about specific files or locations:
 |--compiler-exe         |The GHC executable.                                   |
 |--compiler-tools-bin   |The directory containing binaries specific to a particular compiler.|
 |--config-location      |Stack's project-level YAML configuration file (`stack.yaml`).|
-|--dist-dir             |The dist working directory, relative to the package directory.|
+|--dist-dir             |The dist work directory, relative to the package directory.|
 |--extra-include-dirs   |Extra include directories.                            |
 |--extra-library-dirs   |Extra library directories.                            |
 |--ghc-package-path     |The `GHC_PACKAGE_PATH` environment variable.          |

diff --git a/doc/yaml_configuration.md b/doc/yaml_configuration.md
@@ -439,7 +439,10 @@ build:
     # - "--css=/home/user/my-css"
   open-haddocks: false # --open
   haddock-deps: false # if unspecified, defaults to true if haddock is set
-  haddock-internal: false
+  haddock-for-hackage: false # if specified, implies haddock-internal: false and
+                             # haddock-hyperlink-source: true
+  haddock-internal: false # ignored, if haddock-for-hackage: true
+  haddock-hyperlink-source: true  # ignored, if haddock-for-hackage: true
 
   # These are inadvisable to use in your global configuration, as they make the
   # Stack build command line behave quite differently.

diff --git a/src/Stack/Build/Execute.hs b/src/Stack/Build/Execute.hs
@@ -1673,6 +1673,7 @@ singleBuild ac@ActionContext {..} ee@ExecuteEnv {..} task@Task {..} installedMap
     && maybe True (Set.notMember pname . curatorSkipHaddock) mcurator
   expectHaddockFailure =
       maybe False (Set.member pname . curatorExpectHaddockFailure)
+  isHaddockForHackage = boptsHaddockForHackage eeBuildOpts
   fulfillHaddockExpectations mcurator action
     | expectHaddockFailure mcurator = do
         eres <- tryAny $ action KeepOpen
@@ -1956,11 +1957,9 @@ singleBuild ac@ActionContext {..} ee@ExecuteEnv {..} task@Task {..} installedMap
 
     mcurator <- view $ buildConfigL.to bcCurator
     when (doHaddock mcurator package) $ do
-      announce "haddock"
-      let sourceFlag =
-            [ "--haddock-option=--hyperlinked-source"
-            | boptsHaddockHyperlinkSource eeBuildOpts
-            ]
+      announce $ if isHaddockForHackage
+        then "haddock for Hackage"
+        else "haddock"
 
       -- For GHC 8.4 and later, provide the --quickjump option.
       actualCompiler <- view actualCompilerVersionL
@@ -1970,19 +1969,29 @@ singleBuild ac@ActionContext {..} ee@ExecuteEnv {..} task@Task {..} installedMap
                 | ghcVer >= mkVersion [8, 4] -> ["--haddock-option=--quickjump"]
               _ -> []
 
-      fulfillHaddockExpectations mcurator $ \keep ->
-        cabal0 keep KeepTHLoading $ concat
-          [ [ "haddock"
-            , "--html"
-            , "--hoogle"
-            , "--html-location=../$pkg-$version/"
-            ]
-          , sourceFlag
-          , ["--internal" | boptsHaddockInternal eeBuildOpts]
-          , [ "--haddock-option=" <> opt
-            | opt <- hoAdditionalArgs (boptsHaddockOpts eeBuildOpts) ]
-          , quickjump
-          ]
+      fulfillHaddockExpectations mcurator $ \keep -> do
+        let args = concat
+              (  if isHaddockForHackage
+                   then
+                     [ [ "--for-hackage" ] ]
+                   else
+                     [ [ "--html"
+                       , "--hoogle"
+                       , "--html-location=../$pkg-$version/"
+                       ]
+                     , [ "--haddock-option=--hyperlinked-source"
+                       | boptsHaddockHyperlinkSource eeBuildOpts
+                       ]
+                     , [ "--internal" | boptsHaddockInternal eeBuildOpts ]
+                     , quickjump
+                     ]
+              <> [ [ "--haddock-option=" <> opt
+                   | opt <- hoAdditionalArgs (boptsHaddockOpts eeBuildOpts)
+                   ]
+                 ]
+              )
+
+        cabal0 keep KeepTHLoading $ "haddock" : args
 
     let hasLibrary =
           case packageLibraries package of

diff --git a/src/Stack/Config/Build.hs b/src/Stack/Config/Build.hs
@@ -41,6 +41,7 @@ buildOptsFromMonoid BuildOptsMonoid{..} = BuildOpts
   , boptsHaddockInternal = fromFirstFalse buildMonoidHaddockInternal
   , boptsHaddockHyperlinkSource =
       fromFirstTrue buildMonoidHaddockHyperlinkSource
+  , boptsHaddockForHackage = fromFirstFalse buildMonoidHaddockForHackage
   , boptsInstallExes = fromFirstFalse buildMonoidInstallExes
   , boptsInstallCompilerTool = fromFirstFalse buildMonoidInstallCompilerTool
   , boptsPreFetch = fromFirstFalse buildMonoidPreFetch

diff --git a/src/Stack/Options/BuildMonoidParser.hs b/src/Stack/Options/BuildMonoidParser.hs
@@ -43,6 +43,7 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid
   <*> haddockDeps
   <*> haddockInternal
   <*> haddockHyperlinkSource
+  <*> haddockForHackage
   <*> copyBins
   <*> copyCompilerTool
   <*> preFetch
@@ -142,6 +143,11 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid
     "building hyperlinked source for Haddock documentation (like \
     \'haddock --hyperlinked-source')."
     hide
+  haddockForHackage = firstBoolFlagsFalse
+    "haddock-for-hackage"
+    "building with flags to generate Haddock documentation suitable for upload \
+    \to Hackage."
+    hide
   copyBins = firstBoolFlagsFalse
     "copy-bins"
     "copying binaries to local-bin (see 'stack path')."

diff --git a/src/Stack/Types/BuildOpts.hs b/src/Stack/Types/BuildOpts.hs
@@ -67,8 +67,10 @@ data BuildOpts = BuildOpts
     -- ^ Build haddocks for all symbols and packages, like
     -- @cabal haddock --internal@
   , boptsHaddockHyperlinkSource :: !Bool
-    -- ^ Build hyperlinked source if possible. Fallback to @hscolour@. Disable
-    -- for no sources.
+    -- ^ Build hyperlinked source. Disable for no sources.
+  , boptsHaddockForHackage :: !Bool
+    -- ^ Build with flags to generate Haddock documentation suitable to upload
+    -- to Hackage.
   , boptsInstallExes :: !Bool
     -- ^ Install executables to user path after building?
   , boptsInstallCompilerTool :: !Bool
@@ -122,6 +124,7 @@ defaultBuildOpts = BuildOpts
   , boptsHaddockInternal = defaultFirstFalse buildMonoidHaddockInternal
   , boptsHaddockHyperlinkSource =
       defaultFirstTrue buildMonoidHaddockHyperlinkSource
+  , boptsHaddockForHackage = defaultFirstFalse buildMonoidHaddockForHackage
   , boptsInstallExes = defaultFirstFalse buildMonoidInstallExes
   , boptsInstallCompilerTool = defaultFirstFalse buildMonoidInstallCompilerTool
   , boptsPreFetch = defaultFirstFalse buildMonoidPreFetch
@@ -236,6 +239,7 @@ data BuildOptsMonoid = BuildOptsMonoid
   , buildMonoidHaddockDeps :: !(First Bool)
   , buildMonoidHaddockInternal :: !FirstFalse
   , buildMonoidHaddockHyperlinkSource :: !FirstTrue
+  , buildMonoidHaddockForHackage :: !FirstFalse
   , buildMonoidInstallExes :: !FirstFalse
   , buildMonoidInstallCompilerTool :: !FirstFalse
   , buildMonoidPreFetch :: !FirstFalse
@@ -275,6 +279,8 @@ instance FromJSON (WithJSONWarnings BuildOptsMonoid) where
       FirstFalse <$> o ..:? buildMonoidHaddockInternalArgName
     buildMonoidHaddockHyperlinkSource <-
       FirstTrue <$> o ..:? buildMonoidHaddockHyperlinkSourceArgName
+    buildMonoidHaddockForHackage <-
+      FirstFalse <$> o ..:? buildMonoidHaddockForHackageArgName
     buildMonoidInstallExes <-
       FirstFalse <$> o ..:? buildMonoidInstallExesArgName
     buildMonoidInstallCompilerTool <-
@@ -336,6 +342,9 @@ buildMonoidHaddockInternalArgName = "haddock-internal"
 buildMonoidHaddockHyperlinkSourceArgName :: Text
 buildMonoidHaddockHyperlinkSourceArgName = "haddock-hyperlink-source"
 
+buildMonoidHaddockForHackageArgName :: Text
+buildMonoidHaddockForHackageArgName = "haddock-for-hackage"
+
 buildMonoidInstallExesArgName :: Text
 buildMonoidInstallExesArgName = "copy-bins"