Haddock deprecate hscolour, tweak options

Cabal/ChangeLog.md

@@ -37,6 +37,7 @@
   * Options listed in `ghc-options`, `cc-options`, `ld-options`,
     `cxx-options`, `cpp-options` are not deduplicated anymore
     ([#4449](https://github.com/haskell/cabal/issues/4449)).
+  * Deprecated `cabal hscolour` in favour of `cabal haddock --hyperlink-source` ([#5236](https://github.com/haskell/cabal/pull/5236/)).
 
 ----
 

Cabal/Distribution/Simple/Haddock.hs

@@ -90,6 +90,8 @@ data HaddockArgs = HaddockArgs {
  -- ^ (Template for modules, template for symbols, template for lines).
  argLinkedSource :: Flag Bool,
  -- ^ Generate hyperlinked sources
+ argQuickJump :: Flag Bool,
+ -- ^ Generate quickjump index
  argCssFile :: Flag FilePath,
  -- ^ Optional custom CSS file.
  argContents :: Flag String,
@@ -156,6 +158,7 @@ haddock pkg_descr lbi suffixes flags' = do
             , haddockHtmlLocation = Flag (pkg_url ++ "/docs")
             , haddockContents     = Flag (toPathTemplate pkg_url)
             , haddockLinkedSource = Flag True
+            , haddockQuickJump    = Flag True
             }
         pkg_url       = "/package/$pkg-$version"
         flag f        = fromFlag $ f flags
@@ -176,6 +179,10 @@ haddock pkg_descr lbi suffixes flags' = do
            && version < mkVersion [2,2]) $
          die' verbosity "haddock 2.0 and 2.1 do not support the --hoogle flag."
 
+    when ( flag haddockQuickJump
+           && version < mkVersion [2,19]) $
+         die' verbosity "haddock prior to 2.19 does not support the --quickjump flag."
+
     haddockGhcVersionStr <- getProgramOutput verbosity haddockProg
                               ["--ghc-version"]
     case (simpleParse haddockGhcVersionStr, compilerCompatVersion GHC comp) of
@@ -276,6 +283,7 @@ fromFlags env flags =
                                          ,"src/%{MODULE/./-}.html#line-%{LINE}")
                                else NoFlag,
       argLinkedSource = haddockLinkedSource flags,
+      argQuickJump = haddockQuickJump flags,
       argCssFile = haddockCss flags,
       argContents = fmap (fromPathTemplate . substPathTemplate env)
                     (haddockContents flags),
@@ -545,6 +553,11 @@ renderPureArgs version comp platform args = concat
              . fromFlag . argPackageName $ args
         else []
 
+    , [ "--since-qual=external" | isVersion 2 20 ]
+
+    , [ "--quickjump" | isVersion 2 19
+                      , fromFlag . argQuickJump $ args ]
+
     , [ "--hyperlinked-source" | isVersion 2 17
                                , fromFlag . argLinkedSource $ args ]
 
@@ -751,6 +764,11 @@ hscolour' onNoHsColour haddockTarget pkg_descr lbi suffixes flags =
   where
     go :: ConfiguredProgram -> IO ()
     go hscolourProg = do
+      warn verbosity $
+        "the 'cabal hscolour' command is deprecated in favour of 'cabal " ++
+        "haddock --hyperlink-source' and will be removed in the next major " ++
+        "release."
+
       setupMessage verbosity "Running hscolour for" (packageId pkg_descr)
       createDirectoryIfMissingVerbose verbosity True $
         hscolourPref haddockTarget distPref pkg_descr

Cabal/Distribution/Simple/Setup.hs

@@ -1221,7 +1221,8 @@ hscolourCommand = CommandUI
   , commandSynopsis     =
       "Generate HsColour colourised code, in HTML format."
   , commandDescription  = Just (\_ -> "Requires the hscolour program.\n")
-  , commandNotes        = Nothing
+  , commandNotes        = Just $ \_ ->
+      "Deprecated in favour of 'cabal haddock --hyperlink-source'."
   , commandUsage        = \pname ->
       "Usage: " ++ pname ++ " hscolour [FLAGS]\n"
   , commandDefaultFlags = defaultHscolourFlags
@@ -1376,6 +1377,7 @@ data HaddockFlags = HaddockFlags {
     haddockInternal     :: Flag Bool,
     haddockCss          :: Flag FilePath,
     haddockLinkedSource :: Flag Bool,
+    haddockQuickJump    :: Flag Bool,
     haddockHscolourCss  :: Flag FilePath,
     haddockContents     :: Flag PathTemplate,
     haddockDistPref     :: Flag FilePath,
@@ -1401,6 +1403,7 @@ defaultHaddockFlags  = HaddockFlags {
     haddockInternal     = Flag False,
     haddockCss          = NoFlag,
     haddockLinkedSource = Flag False,
+    haddockQuickJump    = Flag False,
     haddockHscolourCss  = NoFlag,
     haddockContents     = NoFlag,
     haddockDistPref     = NoFlag,
@@ -1513,11 +1516,16 @@ haddockOptions showOrParseArgs =
    haddockCss (\v flags -> flags { haddockCss = v })
    (reqArgFlag "PATH")
 
-  ,option "" ["hyperlink-source","hyperlink-sources"]
+  ,option "" ["hyperlink-source","hyperlink-sources","hyperlinked-source"]
    "Hyperlink the documentation to the source code"
    haddockLinkedSource (\v flags -> flags { haddockLinkedSource = v })
    trueArg
 
+  ,option "" ["quickjump"]
+   "Generate an index for interactive documentation navigation"
+   haddockQuickJump (\v flags -> flags { haddockQuickJump = v })
+   trueArg
+
   ,option "" ["hscolour-css"]
    "Use PATH as the HsColour stylesheet"
    haddockHscolourCss (\v flags -> flags { haddockHscolourCss = v })

cabal-install/Distribution/Client/Config.hs

@@ -408,6 +408,7 @@ instance Semigroup SavedConfig where
         haddockInternal      = combine haddockInternal,
         haddockCss           = combine haddockCss,
         haddockLinkedSource  = combine haddockLinkedSource,
+        haddockQuickJump     = combine haddockQuickJump,
         haddockHscolourCss   = combine haddockHscolourCss,
         haddockContents      = combine haddockContents,
         haddockDistPref      = combine haddockDistPref,

cabal-install/Distribution/Client/ProjectConfig/Legacy.hs

@@ -411,6 +411,7 @@ convertLegacyPerPackageFlags configFlags installFlags haddockFlags =
       haddockInternal           = packageConfigHaddockInternal,
       haddockCss                = packageConfigHaddockCss,
       haddockLinkedSource       = packageConfigHaddockLinkedSource,
+      haddockQuickJump          = packageConfigHaddockQuickJump,
       haddockHscolourCss        = packageConfigHaddockHscolourCss,
       haddockContents           = packageConfigHaddockContents
     } = haddockFlags
@@ -729,6 +730,7 @@ convertToLegacyPerPackageConfig PackageConfig {..} =
       haddockInternal      = packageConfigHaddockInternal,
       haddockCss           = packageConfigHaddockCss,
       haddockLinkedSource  = packageConfigHaddockLinkedSource,
+      haddockQuickJump     = packageConfigHaddockQuickJump,
       haddockHscolourCss   = packageConfigHaddockHscolourCss,
       haddockContents      = packageConfigHaddockContents,
       haddockDistPref      = mempty,
@@ -1004,7 +1006,7 @@ legacyPackageConfigFieldDescrs =
       [ "hoogle", "html", "html-location"
       , "foreign-libraries"
       , "executables", "tests", "benchmarks", "all", "internal", "css"
-      , "hyperlink-source", "hscolour-css"
+      , "hyperlink-source", "quickjump", "hscolour-css"
       , "contents-location", "keep-temp-files"
       ]
   . commandOptionsToFields

cabal-install/Distribution/Client/ProjectConfig/Types.hs

@@ -270,6 +270,7 @@ data PackageConfig
        packageConfigHaddockInternal     :: Flag Bool, --TODO: [required eventually] use this
        packageConfigHaddockCss          :: Flag FilePath, --TODO: [required eventually] use this
        packageConfigHaddockLinkedSource :: Flag Bool, --TODO: [required eventually] use this
+       packageConfigHaddockQuickJump    :: Flag Bool, --TODO: [required eventually] use this
        packageConfigHaddockHscolourCss  :: Flag FilePath, --TODO: [required eventually] use this
        packageConfigHaddockContents     :: Flag PathTemplate, --TODO: [required eventually] use this
        packageConfigHaddockForHackage   :: Flag HaddockTarget

cabal-install/Distribution/Client/ProjectPlanning.hs

@@ -1828,6 +1828,7 @@ elaborateInstallPlan verbosity platform compiler compilerprogdb pkgConfigDB
         elabHaddockInternal     = perPkgOptionFlag pkgid False packageConfigHaddockInternal
         elabHaddockCss          = perPkgOptionMaybe pkgid packageConfigHaddockCss
         elabHaddockLinkedSource = perPkgOptionFlag pkgid False packageConfigHaddockLinkedSource
+        elabHaddockQuickJump    = perPkgOptionFlag pkgid False packageConfigHaddockQuickJump
         elabHaddockHscolourCss  = perPkgOptionMaybe pkgid packageConfigHaddockHscolourCss
         elabHaddockContents     = perPkgOptionMaybe pkgid packageConfigHaddockContents
 
@@ -3441,6 +3442,7 @@ setupHsHaddockFlags (ElaboratedConfiguredPackage{..}) _ verbosity builddir =
       haddockInternal      = toFlag elabHaddockInternal,
       haddockCss           = maybe mempty toFlag elabHaddockCss,
       haddockLinkedSource  = toFlag elabHaddockLinkedSource,
+      haddockQuickJump     = toFlag elabHaddockQuickJump,
       haddockHscolourCss   = maybe mempty toFlag elabHaddockHscolourCss,
       haddockContents      = maybe mempty toFlag elabHaddockContents,
       haddockDistPref      = toFlag builddir,

cabal-install/Distribution/Client/ProjectPlanning/Types.hs

@@ -277,6 +277,7 @@ data ElaboratedConfiguredPackage
        elabHaddockInternal       :: Bool,
        elabHaddockCss            :: Maybe FilePath,
        elabHaddockLinkedSource   :: Bool,
+       elabHaddockQuickJump      :: Bool,
        elabHaddockHscolourCss    :: Maybe FilePath,
        elabHaddockContents       :: Maybe PathTemplate,
 

cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs

@@ -551,6 +551,7 @@ instance Arbitrary PackageConfig where
         <*> arbitrary
         <*> arbitraryFlag arbitraryShortToken
         <*> arbitrary
+        <*> arbitrary
         <*> arbitraryFlag arbitraryShortToken
         <*> arbitrary
         <*> arbitrary
@@ -602,6 +603,7 @@ instance Arbitrary PackageConfig where
                          , packageConfigHaddockInternal = x36
                          , packageConfigHaddockCss = x37
                          , packageConfigHaddockLinkedSource = x38
+                         , packageConfigHaddockQuickJump = x43
                          , packageConfigHaddockHscolourCss = x39
                          , packageConfigHaddockContents = x40
                          , packageConfigHaddockForHackage = x41 } =
@@ -647,6 +649,7 @@ instance Arbitrary PackageConfig where
                       , packageConfigHaddockInternal = x36'
                       , packageConfigHaddockCss = fmap getNonEmpty x37'
                       , packageConfigHaddockLinkedSource = x38'
+                      , packageConfigHaddockQuickJump = x43'
                       , packageConfigHaddockHscolourCss = fmap getNonEmpty x39'
                       , packageConfigHaddockContents = x40'
                       , packageConfigHaddockForHackage = x41' }
@@ -657,7 +660,7 @@ instance Arbitrary PackageConfig where
          ((x20', x20_1', x21', x22', x23', x24'),
           (x25', x26', x27', x28', x29'),
           (x30', x31', x32', (x33', x33_1'), x34'),
-          (x35', x36', x37', x38', x39'),
+          (x35', x36', x37', x38', x43', x39'),
           (x40', x41')))
           <- shrink
              (((preShrink_Paths x00, preShrink_Args x01, x02, x03, x04),
@@ -670,7 +673,7 @@ instance Arbitrary PackageConfig where
                ((x20, x20_1, x21, x22, x23, x24),
                  (x25, x26, x27, x28, x29),
                  (x30, x31, x32, (x33, x33_1), x34),
-                 (x35, x36, fmap NonEmpty x37, x38, fmap NonEmpty x39),
+                 (x35, x36, fmap NonEmpty x37, x38, x43, fmap NonEmpty x39),
                  (x40, x41)))
       ]
       where