From 6922cfc34071f735ad6d9dad0bab695822235ccc Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Tue, 27 Mar 2018 09:28:43 -0700 Subject: [PATCH 1/6] Deprecate hscolour, add hyperlink-source synonyms * warning in hscolour's description * warning when hscolour is run * added 'hyperlinked-source' (the name Haddock has for the option) as a synonym for 'hyperlink-source' Follows up comments from https://github.com/haskell/cabal/pull/5140. --- Cabal/ChangeLog.md | 1 + Cabal/Distribution/Simple/Haddock.hs | 5 +++++ Cabal/Distribution/Simple/Setup.hs | 5 +++-- 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/Cabal/ChangeLog.md b/Cabal/ChangeLog.md index 6c422e45904..885ca99e07e 100644 --- a/Cabal/ChangeLog.md +++ b/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/)). ---- diff --git a/Cabal/Distribution/Simple/Haddock.hs b/Cabal/Distribution/Simple/Haddock.hs index 5d5938e24f2..09be35a448a 100644 --- a/Cabal/Distribution/Simple/Haddock.hs +++ b/Cabal/Distribution/Simple/Haddock.hs @@ -751,6 +751,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 diff --git a/Cabal/Distribution/Simple/Setup.hs b/Cabal/Distribution/Simple/Setup.hs index d8047d145e3..b3e587e898e 100644 --- a/Cabal/Distribution/Simple/Setup.hs +++ b/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 @@ -1513,7 +1514,7 @@ 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 From f14bb2cb8df26531f444a8c6229e0b7c495c7082 Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Tue, 27 Mar 2018 09:35:05 -0700 Subject: [PATCH 2/6] Pass in 'since-qual' for new enough Haddock Now that Haddock has support for package-aware since annotations, we want to pass in the option that omits the package name on since annotations for the current package. --- Cabal/Distribution/Simple/Haddock.hs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Cabal/Distribution/Simple/Haddock.hs b/Cabal/Distribution/Simple/Haddock.hs index 09be35a448a..a6a719f2739 100644 --- a/Cabal/Distribution/Simple/Haddock.hs +++ b/Cabal/Distribution/Simple/Haddock.hs @@ -545,6 +545,8 @@ renderPureArgs version comp platform args = concat . fromFlag . argPackageName $ args else [] + , [ "--since-qual=external" | version >= mkVersion [2, 19, 1] ] + , [ "--hyperlinked-source" | isVersion 2 17 , fromFlag . argLinkedSource $ args ] From e7acacc38946df188555cdc9c74d9bd6d967d067 Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Tue, 27 Mar 2018 10:46:38 -0700 Subject: [PATCH 3/6] Add a 'quickjump' option, implied by 'for-hackage' This options only works for Haddock >=2.19. --- Cabal/Distribution/Simple/Haddock.hs | 11 ++++++++++ Cabal/Distribution/Simple/Setup.hs | 7 ++++++ cabal-install/Distribution/Client/Config.hs | 1 + .../Client/ProjectConfig/Legacy.hs | 2 ++ .../Client/ProjectConfig/Types.hs | 1 + .../Distribution/Client/ProjectPlanning.hs | 2 ++ .../Client/ProjectPlanning/Types.hs | 1 + .../Distribution/Client/ProjectConfig.hs | 22 ++++++++++--------- 8 files changed, 37 insertions(+), 10 deletions(-) diff --git a/Cabal/Distribution/Simple/Haddock.hs b/Cabal/Distribution/Simple/Haddock.hs index a6a719f2739..3cc960406c9 100644 --- a/Cabal/Distribution/Simple/Haddock.hs +++ b/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), @@ -547,6 +555,9 @@ renderPureArgs version comp platform args = concat , [ "--since-qual=external" | version >= mkVersion [2, 19, 1] ] + , [ "--quickjump" | isVersion 2 19 + , fromFlag . argQuickJump $ args ] + , [ "--hyperlinked-source" | isVersion 2 17 , fromFlag . argLinkedSource $ args ] diff --git a/Cabal/Distribution/Simple/Setup.hs b/Cabal/Distribution/Simple/Setup.hs index b3e587e898e..4640c1d71ae 100644 --- a/Cabal/Distribution/Simple/Setup.hs +++ b/Cabal/Distribution/Simple/Setup.hs @@ -1377,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, @@ -1402,6 +1403,7 @@ defaultHaddockFlags = HaddockFlags { haddockInternal = Flag False, haddockCss = NoFlag, haddockLinkedSource = Flag False, + haddockQuickJump = Flag False, haddockHscolourCss = NoFlag, haddockContents = NoFlag, haddockDistPref = NoFlag, @@ -1519,6 +1521,11 @@ haddockOptions showOrParseArgs = 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 }) diff --git a/cabal-install/Distribution/Client/Config.hs b/cabal-install/Distribution/Client/Config.hs index 07ce560eb93..9cf4b043380 100644 --- a/cabal-install/Distribution/Client/Config.hs +++ b/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, diff --git a/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs b/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs index ca00f78580e..7be543f9f81 100644 --- a/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs +++ b/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, diff --git a/cabal-install/Distribution/Client/ProjectConfig/Types.hs b/cabal-install/Distribution/Client/ProjectConfig/Types.hs index 29a8fcf4f7d..c7c62acbd53 100644 --- a/cabal-install/Distribution/Client/ProjectConfig/Types.hs +++ b/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 diff --git a/cabal-install/Distribution/Client/ProjectPlanning.hs b/cabal-install/Distribution/Client/ProjectPlanning.hs index 40fb6bd854d..820872c315a 100644 --- a/cabal-install/Distribution/Client/ProjectPlanning.hs +++ b/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, diff --git a/cabal-install/Distribution/Client/ProjectPlanning/Types.hs b/cabal-install/Distribution/Client/ProjectPlanning/Types.hs index 0e02a12ba67..4b85fe8e4e9 100644 --- a/cabal-install/Distribution/Client/ProjectPlanning/Types.hs +++ b/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, diff --git a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs b/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs index 80d99b14b97..8f75a45b427 100644 --- a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs +++ b/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs @@ -602,9 +602,10 @@ instance Arbitrary PackageConfig where , packageConfigHaddockInternal = x36 , packageConfigHaddockCss = x37 , packageConfigHaddockLinkedSource = x38 - , packageConfigHaddockHscolourCss = x39 - , packageConfigHaddockContents = x40 - , packageConfigHaddockForHackage = x41 } = + , packageConfigHaddockQuickJump = x39 + , packageConfigHaddockHscolourCss = x40 + , packageConfigHaddockContents = x41 + , packageConfigHaddockForHackage = x42 } = [ PackageConfig { packageConfigProgramPaths = postShrink_Paths x00' , packageConfigProgramArgs = postShrink_Args x01' , packageConfigProgramPathExtra = x02' @@ -647,9 +648,10 @@ instance Arbitrary PackageConfig where , packageConfigHaddockInternal = x36' , packageConfigHaddockCss = fmap getNonEmpty x37' , packageConfigHaddockLinkedSource = x38' - , packageConfigHaddockHscolourCss = fmap getNonEmpty x39' - , packageConfigHaddockContents = x40' - , packageConfigHaddockForHackage = x41' } + , packageConfigHaddockQuickJump = x39' + , packageConfigHaddockHscolourCss = fmap getNonEmpty x40' + , packageConfigHaddockContents = x41' + , packageConfigHaddockForHackage = x42' } | (((x00', x01', x02', x03', x04'), (x05', x42', x06', x07', x08', x09'), (x10', x11', x12', x13', x14'), @@ -657,8 +659,8 @@ 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'), - (x40', x41'))) + (x35', x36', x37', x38', x39', x40'), + (x41', x42'))) <- shrink (((preShrink_Paths x00, preShrink_Args x01, x02, x03, x04), (x05, x42, x06, x07, x08, x09), @@ -670,8 +672,8 @@ 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), - (x40, x41))) + (x35, x36, fmap NonEmpty x37, x38, x39, fmap NonEmpty x40), + (x41, x42))) ] where preShrink_Paths = Map.map NonEmpty From 3157d0d68d424ab6f1196b10be2dc35ea239f2c9 Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Tue, 27 Mar 2018 12:59:45 -0700 Subject: [PATCH 4/6] fix test --- .../Client/ProjectConfig/Legacy.hs | 2 +- .../Distribution/Client/ProjectConfig.hs | 25 ++++++++++--------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs b/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs index 7be543f9f81..e5747a0d4c2 100644 --- a/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs +++ b/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs @@ -1006,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 diff --git a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs b/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs index 8f75a45b427..2885c9ed930 100644 --- a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs +++ b/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,10 +603,10 @@ instance Arbitrary PackageConfig where , packageConfigHaddockInternal = x36 , packageConfigHaddockCss = x37 , packageConfigHaddockLinkedSource = x38 - , packageConfigHaddockQuickJump = x39 - , packageConfigHaddockHscolourCss = x40 - , packageConfigHaddockContents = x41 - , packageConfigHaddockForHackage = x42 } = + , packageConfigHaddockQuickJump = x43 + , packageConfigHaddockHscolourCss = x39 + , packageConfigHaddockContents = x40 + , packageConfigHaddockForHackage = x41 } = [ PackageConfig { packageConfigProgramPaths = postShrink_Paths x00' , packageConfigProgramArgs = postShrink_Args x01' , packageConfigProgramPathExtra = x02' @@ -648,10 +649,10 @@ instance Arbitrary PackageConfig where , packageConfigHaddockInternal = x36' , packageConfigHaddockCss = fmap getNonEmpty x37' , packageConfigHaddockLinkedSource = x38' - , packageConfigHaddockQuickJump = x39' - , packageConfigHaddockHscolourCss = fmap getNonEmpty x40' - , packageConfigHaddockContents = x41' - , packageConfigHaddockForHackage = x42' } + , packageConfigHaddockQuickJump = x43' + , packageConfigHaddockHscolourCss = fmap getNonEmpty x39' + , packageConfigHaddockContents = x40' + , packageConfigHaddockForHackage = x41' } | (((x00', x01', x02', x03', x04'), (x05', x42', x06', x07', x08', x09'), (x10', x11', x12', x13', x14'), @@ -659,8 +660,8 @@ 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', x40'), - (x41', x42'))) + (x35', x36', x37', x38', x43', x39'), + (x40', x41'))) <- shrink (((preShrink_Paths x00, preShrink_Args x01, x02, x03, x04), (x05, x42, x06, x07, x08, x09), @@ -672,8 +673,8 @@ 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, x39, fmap NonEmpty x40), - (x41, x42))) + (x35, x36, fmap NonEmpty x37, x38, x43, fmap NonEmpty x39), + (x40, x41))) ] where preShrink_Paths = Map.map NonEmpty From 8d87d3e779772f721d50ee6897e190eaddf07065 Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Thu, 29 Mar 2018 07:58:27 -0700 Subject: [PATCH 5/6] Bump '--since-qual' to Haddock 2.20 --- Cabal/Distribution/Simple/Haddock.hs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Cabal/Distribution/Simple/Haddock.hs b/Cabal/Distribution/Simple/Haddock.hs index 3cc960406c9..5437d228472 100644 --- a/Cabal/Distribution/Simple/Haddock.hs +++ b/Cabal/Distribution/Simple/Haddock.hs @@ -180,7 +180,7 @@ haddock pkg_descr lbi suffixes flags' = do die' verbosity "haddock 2.0 and 2.1 do not support the --hoogle flag." when ( flag haddockQuickJump - && version < mkVersion [2,19]) $ + && version < mkVersion [2,20]) $ die' verbosity "haddock prior to 2.19 does not support the --quickjump flag." haddockGhcVersionStr <- getProgramOutput verbosity haddockProg @@ -553,7 +553,7 @@ renderPureArgs version comp platform args = concat . fromFlag . argPackageName $ args else [] - , [ "--since-qual=external" | version >= mkVersion [2, 19, 1] ] + , [ "--since-qual=external" | version >= mkVersion 2 20 ] , [ "--quickjump" | isVersion 2 19 , fromFlag . argQuickJump $ args ] From 0a3891e98aedb00dc25e7e02460f8b3f0c042ac4 Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Thu, 29 Mar 2018 08:17:01 -0700 Subject: [PATCH 6/6] Typo --- Cabal/Distribution/Simple/Haddock.hs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Cabal/Distribution/Simple/Haddock.hs b/Cabal/Distribution/Simple/Haddock.hs index 5437d228472..0b82a989c7e 100644 --- a/Cabal/Distribution/Simple/Haddock.hs +++ b/Cabal/Distribution/Simple/Haddock.hs @@ -180,7 +180,7 @@ haddock pkg_descr lbi suffixes flags' = do die' verbosity "haddock 2.0 and 2.1 do not support the --hoogle flag." when ( flag haddockQuickJump - && version < mkVersion [2,20]) $ + && version < mkVersion [2,19]) $ die' verbosity "haddock prior to 2.19 does not support the --quickjump flag." haddockGhcVersionStr <- getProgramOutput verbosity haddockProg @@ -553,7 +553,7 @@ renderPureArgs version comp platform args = concat . fromFlag . argPackageName $ args else [] - , [ "--since-qual=external" | version >= mkVersion 2 20 ] + , [ "--since-qual=external" | isVersion 2 20 ] , [ "--quickjump" | isVersion 2 19 , fromFlag . argQuickJump $ args ]