From 905b30d1c0441bf443901d7e9bfa9edb58259ece Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 00:00:26 +0200 Subject: [PATCH 01/19] Refactor Distribution.Simple.Haddock.haddocks --- Cabal/src/Distribution/Simple/Haddock.hs | 88 ++++++++++++++---------- 1 file changed, 53 insertions(+), 35 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index 985d79ea9be..590e7d8f3a5 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -1,5 +1,6 @@ {-# LANGUAGE DeriveGeneric #-} {-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NamedFieldPuns #-} {-# LANGUAGE RankNTypes #-} ----------------------------------------------------------------------------- @@ -134,10 +135,55 @@ unDir = normalise . unDir' type Template = String data Output = Html | Hoogle + deriving Eq -- ------------------------------------------------------------------------------ -- Haddock support +-- | Get Haddock program and check if it matches the request +getHaddockProg :: Verbosity + -> ProgramDb + -> Compiler + -> HaddockArgs + -> Flag Bool -- ^ quickjump feature + -> IO (ConfiguredProgram, Version) +getHaddockProg verbosity programDb comp args quickJumpFlag = do + let HaddockArgs { argQuickJump + , argOutput + } = args + hoogle = Hoogle `elem` fromFlagOrDefault [] argOutput + + (haddockProg, version, _) <- + requireProgramVersion verbosity haddockProgram + (orLaterVersion (mkVersion [2,0])) programDb + + -- various sanity checks + when (hoogle && version < mkVersion [2,2]) $ + die' verbosity "Haddock 2.0 and 2.1 do not support the --hoogle flag." + + when (fromFlag argQuickJump && version < mkVersion [2,19]) $ do + let msg = "Haddock prior to 2.19 does not support the --quickjump flag." + alt = "The generated documentation won't have the QuickJump feature." + if Flag True == quickJumpFlag + then die' verbosity msg + else warn verbosity (msg ++ "\n" ++ alt) + + haddockGhcVersionStr <- getProgramOutput verbosity haddockProg + ["--ghc-version"] + case (simpleParsec haddockGhcVersionStr, compilerCompatVersion GHC comp) of + (Nothing, _) -> die' verbosity "Could not get GHC version from Haddock" + (_, Nothing) -> die' verbosity "Could not get GHC version from compiler" + (Just haddockGhcVersion, Just ghcVersion) + | haddockGhcVersion == ghcVersion -> return () + | otherwise -> die' verbosity $ + "Haddock's internal GHC version must match the configured " + ++ "GHC version.\n" + ++ "The GHC version is " ++ prettyShow ghcVersion ++ " but " + ++ "haddock is using GHC version " ++ prettyShow haddockGhcVersion + + return (haddockProg, version) + + haddock :: PackageDescription -> LocalBuildInfo -> [PPSuffixHandler] @@ -181,36 +227,14 @@ haddock pkg_descr lbi suffixes flags' = do haddockTarget = fromFlagOrDefault ForDevelopment (haddockForHackage flags') - (haddockProg, version, _) <- - requireProgramVersion verbosity haddockProgram - (orLaterVersion (mkVersion [2,0])) (withPrograms lbi) - - -- various sanity checks - when (flag haddockHoogle && 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]) $ do - let msg = "Haddock prior to 2.19 does not support the --quickjump flag." - alt = "The generated documentation won't have the QuickJump feature." - if Flag True == quickJmpFlag - then die' verbosity msg - else warn verbosity (msg ++ "\n" ++ alt) - - haddockGhcVersionStr <- getProgramOutput verbosity haddockProg - ["--ghc-version"] - case (simpleParsec haddockGhcVersionStr, compilerCompatVersion GHC comp) of - (Nothing, _) -> die' verbosity "Could not get GHC version from Haddock" - (_, Nothing) -> die' verbosity "Could not get GHC version from compiler" - (Just haddockGhcVersion, Just ghcVersion) - | haddockGhcVersion == ghcVersion -> return () - | otherwise -> die' verbosity $ - "Haddock's internal GHC version must match the configured " - ++ "GHC version.\n" - ++ "The GHC version is " ++ prettyShow ghcVersion ++ " but " - ++ "haddock is using GHC version " ++ prettyShow haddockGhcVersion + libdirArgs <- getGhcLibDir verbosity lbi + let commonArgs = mconcat + [ libdirArgs + , fromFlags (haddockTemplateEnv lbi (packageId pkg_descr)) flags + , fromPackageDescription haddockTarget pkg_descr ] - -- the tools match the requests, we can proceed + (haddockProg, version) <- + getHaddockProg verbosity (withPrograms lbi) comp commonArgs quickJmpFlag -- We fall back to using HsColour only for versions of Haddock which don't -- support '--hyperlinked-sources'. @@ -218,12 +242,6 @@ haddock pkg_descr lbi suffixes flags' = do hscolour' (warn verbosity) haddockTarget pkg_descr lbi suffixes (defaultHscolourFlags `mappend` haddockToHscolour flags) - libdirArgs <- getGhcLibDir verbosity lbi - let commonArgs = mconcat - [ libdirArgs - , fromFlags (haddockTemplateEnv lbi (packageId pkg_descr)) flags - , fromPackageDescription haddockTarget pkg_descr ] - targets <- readTargetInfos verbosity pkg_descr lbi (haddockArgs flags) let From 1023d65649781ec3a5941346867260046f9a6d71 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 06:27:49 +0200 Subject: [PATCH 02/19] Extend HaddockFlags Added: * `haddockIndex`: passed as '--use-index' to 'haddock' * `haddockBaseUrl` : passed as '--base-url' to haddock' --- Cabal/src/Distribution/Simple/Haddock.hs | 11 +++++++++++ Cabal/src/Distribution/Simple/Setup.hs | 16 ++++++++++++++++ cabal-install/src/Distribution/Client/Config.hs | 2 ++ .../src/Distribution/Client/PackageHash.hs | 6 +++++- .../Distribution/Client/ProjectConfig/Legacy.hs | 8 ++++++-- .../Distribution/Client/ProjectConfig/Types.hs | 2 ++ .../src/Distribution/Client/ProjectPlanning.hs | 8 +++++++- .../Distribution/Client/ProjectPlanning/Types.hs | 2 ++ cabal-install/src/Distribution/Client/Setup.hs | 2 +- .../Distribution/Client/ProjectConfig.hs | 10 ++++++++-- 10 files changed, 60 insertions(+), 7 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index 590e7d8f3a5..4b2e2f29e9f 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -105,6 +105,10 @@ data HaddockArgs = HaddockArgs { -- ^ Optional custom CSS file. argContents :: Flag String, -- ^ Optional URL to contents page. + argIndex :: Flag String, + -- ^ Optional URL to index page. + argBaseUrl :: Flag String, + -- ^ Optional base url from which static files will be loaded. argVerbose :: Any, argOutput :: Flag [Output], -- ^ HTML or Hoogle doc or both? Required. @@ -352,6 +356,9 @@ fromFlags env flags = argCssFile = haddockCss flags, argContents = fmap (fromPathTemplate . substPathTemplate env) (haddockContents flags), + argIndex = fmap (fromPathTemplate . substPathTemplate env) + (haddockIndex flags), + argBaseUrl = haddockBaseUrl flags, argVerbose = maybe mempty (Any . (>= deafening)) . flagToMaybe $ haddockVerbosity flags, argOutput = @@ -659,6 +666,10 @@ renderPureArgs version comp platform args = concat , maybe [] ((:[]) . ("--use-contents="++)) . flagToMaybe . argContents $ args + , maybe [] ((:[]) . ("--use-index="++)) . flagToMaybe . argIndex $ args + + , maybe [] ((:[]) . ("--base-url="++)) . flagToMaybe . argBaseUrl $ args + , bool [] [verbosityFlag] . getAny . argVerbose $ args , map (\o -> case o of Hoogle -> "--hoogle"; Html -> "--html") diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index 6540d1e3685..b15a444e3d1 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -1376,10 +1376,12 @@ data HaddockFlags = HaddockFlags { haddockQuickJump :: Flag Bool, haddockHscolourCss :: Flag FilePath, haddockContents :: Flag PathTemplate, + haddockIndex :: Flag PathTemplate, haddockDistPref :: Flag FilePath, haddockKeepTempFiles:: Flag Bool, haddockVerbosity :: Flag Verbosity, haddockCabalFilePath :: Flag FilePath, + haddockBaseUrl :: Flag String, haddockArgs :: [String] } deriving (Show, Generic, Typeable) @@ -1406,6 +1408,8 @@ defaultHaddockFlags = HaddockFlags { haddockKeepTempFiles= Flag False, haddockVerbosity = Flag normal, haddockCabalFilePath = mempty, + haddockIndex = NoFlag, + haddockBaseUrl = NoFlag, haddockArgs = mempty } @@ -1533,6 +1537,18 @@ haddockOptions showOrParseArgs = (reqArg' "URL" (toFlag . toPathTemplate) (flagToList . fmap fromPathTemplate)) + + ,option "" ["index-location"] + "Use a separately-generated HTML index" + haddockIndex (\v flags -> flags { haddockIndex = v}) + (reqArg' "URL" + (toFlag . toPathTemplate) + (flagToList . fmap fromPathTemplate)) + + ,option "" ["base-url"] + "Base URL for static files." + haddockBaseUrl (\v flags -> flags { haddockBaseUrl = v}) + (reqArgFlag "URL") ] emptyHaddockFlags :: HaddockFlags diff --git a/cabal-install/src/Distribution/Client/Config.hs b/cabal-install/src/Distribution/Client/Config.hs index 17eb0c0550f..ce989e0cf50 100644 --- a/cabal-install/src/Distribution/Client/Config.hs +++ b/cabal-install/src/Distribution/Client/Config.hs @@ -487,6 +487,8 @@ instance Semigroup SavedConfig where haddockKeepTempFiles = combine haddockKeepTempFiles, haddockVerbosity = combine haddockVerbosity, haddockCabalFilePath = combine haddockCabalFilePath, + haddockIndex = combine haddockIndex, + haddockBaseUrl = combine haddockBaseUrl, haddockArgs = lastNonEmpty haddockArgs } where diff --git a/cabal-install/src/Distribution/Client/PackageHash.hs b/cabal-install/src/Distribution/Client/PackageHash.hs index 23df740b668..0ec31101a48 100644 --- a/cabal-install/src/Distribution/Client/PackageHash.hs +++ b/cabal-install/src/Distribution/Client/PackageHash.hs @@ -215,7 +215,9 @@ data PackageHashConfigInputs = PackageHashConfigInputs { pkgHashHaddockCss :: Maybe FilePath, pkgHashHaddockLinkedSource :: Bool, pkgHashHaddockQuickJump :: Bool, - pkgHashHaddockContents :: Maybe PathTemplate + pkgHashHaddockContents :: Maybe PathTemplate, + pkgHashHaddockIndex :: Maybe PathTemplate, + pkgHashHaddockBaseUrl :: Maybe String -- TODO: [required eventually] pkgHashToolsVersions ? -- TODO: [required eventually] pkgHashToolsExtraOptions ? @@ -309,6 +311,8 @@ renderPackageHashInputs PackageHashInputs{ , opt "haddock-hyperlink-source" False prettyShow pkgHashHaddockLinkedSource , opt "haddock-quickjump" False prettyShow pkgHashHaddockQuickJump , opt "haddock-contents-location" Nothing (maybe "" fromPathTemplate) pkgHashHaddockContents + , opt "haddock-index-location" Nothing (maybe "" fromPathTemplate) pkgHashHaddockIndex + , opt "haddock-base-url" Nothing (fromMaybe "") pkgHashHaddockBaseUrl ] ++ Map.foldrWithKey (\prog args acc -> opt (prog ++ "-options") [] unwords args : acc) [] pkgHashProgramArgs where diff --git a/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs b/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs index 2ed03cc6888..ac0a9ec918c 100644 --- a/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs +++ b/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs @@ -595,7 +595,9 @@ convertLegacyPerPackageFlags configFlags installFlags haddockLinkedSource = packageConfigHaddockLinkedSource, haddockQuickJump = packageConfigHaddockQuickJump, haddockHscolourCss = packageConfigHaddockHscolourCss, - haddockContents = packageConfigHaddockContents + haddockContents = packageConfigHaddockContents, + haddockIndex = packageConfigHaddockIndex, + haddockBaseUrl = packageConfigHaddockBaseUrl } = haddockFlags TestFlags { @@ -956,6 +958,8 @@ convertToLegacyPerPackageConfig PackageConfig {..} = haddockKeepTempFiles = mempty, haddockVerbosity = mempty, haddockCabalFilePath = mempty, + haddockIndex = packageConfigHaddockIndex, + haddockBaseUrl = packageConfigHaddockBaseUrl, haddockArgs = mempty } @@ -1275,7 +1279,7 @@ legacyPackageConfigFieldDescrs = , "foreign-libraries" , "executables", "tests", "benchmarks", "all", "internal", "css" , "hyperlink-source", "quickjump", "hscolour-css" - , "contents-location", "keep-temp-files" + , "contents-location", "index-location", "keep-temp-files", "base-url" ] . commandOptionsToFields ) (haddockOptions ParseArgs) diff --git a/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs b/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs index 001aeede754..464f4b3744f 100644 --- a/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs +++ b/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs @@ -287,6 +287,8 @@ data PackageConfig packageConfigHaddockQuickJump :: Flag Bool, --TODO: [required eventually] use this packageConfigHaddockHscolourCss :: Flag FilePath, --TODO: [required eventually] use this packageConfigHaddockContents :: Flag PathTemplate, --TODO: [required eventually] use this + packageConfigHaddockIndex :: Flag PathTemplate, --TODO: [required eventually] use this + packageConfigHaddockBaseUrl :: Flag String, --TODO: [required eventually] use this packageConfigHaddockForHackage :: Flag HaddockTarget, -- Test options packageConfigTestHumanLog :: Flag PathTemplate, diff --git a/cabal-install/src/Distribution/Client/ProjectPlanning.hs b/cabal-install/src/Distribution/Client/ProjectPlanning.hs index ab4bd57063d..20a1ab1e864 100644 --- a/cabal-install/src/Distribution/Client/ProjectPlanning.hs +++ b/cabal-install/src/Distribution/Client/ProjectPlanning.hs @@ -1954,6 +1954,8 @@ elaborateInstallPlan verbosity platform compiler compilerprogdb pkgConfigDB elabHaddockQuickJump = perPkgOptionFlag pkgid False packageConfigHaddockQuickJump elabHaddockHscolourCss = perPkgOptionMaybe pkgid packageConfigHaddockHscolourCss elabHaddockContents = perPkgOptionMaybe pkgid packageConfigHaddockContents + elabHaddockIndex = perPkgOptionMaybe pkgid packageConfigHaddockIndex + elabHaddockBaseUrl = perPkgOptionMaybe pkgid packageConfigHaddockBaseUrl elabTestMachineLog = perPkgOptionMaybe pkgid packageConfigTestMachineLog elabTestHumanLog = perPkgOptionMaybe pkgid packageConfigTestHumanLog @@ -3762,6 +3764,8 @@ setupHsHaddockFlags (ElaboratedConfiguredPackage{..}) _ verbosity builddir = haddockKeepTempFiles = mempty, --TODO: from build settings haddockVerbosity = toFlag verbosity, haddockCabalFilePath = mempty, + haddockIndex = maybe mempty toFlag elabHaddockIndex, + haddockBaseUrl = maybe mempty toFlag elabHaddockBaseUrl, haddockArgs = mempty } @@ -3914,7 +3918,9 @@ packageHashConfigInputs shared@ElaboratedSharedConfig{..} pkg = pkgHashHaddockCss = elabHaddockCss, pkgHashHaddockLinkedSource = elabHaddockLinkedSource, pkgHashHaddockQuickJump = elabHaddockQuickJump, - pkgHashHaddockContents = elabHaddockContents + pkgHashHaddockContents = elabHaddockContents, + pkgHashHaddockIndex = elabHaddockIndex, + pkgHashHaddockBaseUrl = elabHaddockBaseUrl } where ElaboratedConfiguredPackage{..} = normaliseConfiguredPackage shared pkg diff --git a/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs b/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs index 3b1472130f5..02b8bf774ba 100644 --- a/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs +++ b/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs @@ -292,6 +292,8 @@ data ElaboratedConfiguredPackage elabHaddockQuickJump :: Bool, elabHaddockHscolourCss :: Maybe FilePath, elabHaddockContents :: Maybe PathTemplate, + elabHaddockIndex :: Maybe PathTemplate, + elabHaddockBaseUrl :: Maybe String, elabTestMachineLog :: Maybe PathTemplate, elabTestHumanLog :: Maybe PathTemplate, diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs index f309a6bf1f6..1ddb9995494 100644 --- a/cabal-install/src/Distribution/Client/Setup.hs +++ b/cabal-install/src/Distribution/Client/Setup.hs @@ -1749,7 +1749,7 @@ haddockOptions showOrParseArgs , name `elem` ["hoogle", "html", "html-location" ,"executables", "tests", "benchmarks", "all", "internal", "css" ,"hyperlink-source", "quickjump", "hscolour-css" - ,"contents-location", "for-hackage"] + ,"contents-location", "use-index", "for-hackage", "base-url"] ] testOptions :: ShowOrParseArgs -> [OptionField TestFlags] diff --git a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs b/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs index 855386febd3..9d2acf3c753 100644 --- a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs +++ b/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs @@ -571,6 +571,8 @@ instance Arbitrary PackageConfig where <*> arbitraryFlag arbitraryShortToken <*> arbitrary <*> arbitrary + <*> arbitraryFlag arbitraryShortToken + <*> arbitrary <*> arbitrary <*> arbitrary <*> arbitrary @@ -634,6 +636,8 @@ instance Arbitrary PackageConfig where , packageConfigHaddockHscolourCss = x39 , packageConfigHaddockContents = x40 , packageConfigHaddockForHackage = x41 + , packageConfigHaddockIndex = x54 + , packageConfigHaddockBaseUrl = x55 , packageConfigTestHumanLog = x44 , packageConfigTestMachineLog = x45 , packageConfigTestShowDetails = x46 @@ -691,6 +695,8 @@ instance Arbitrary PackageConfig where , packageConfigHaddockHscolourCss = fmap getNonEmpty x39' , packageConfigHaddockContents = x40' , packageConfigHaddockForHackage = x41' + , packageConfigHaddockIndex = x54' + , packageConfigHaddockBaseUrl = x55' , packageConfigTestHumanLog = x44' , packageConfigTestMachineLog = x45' , packageConfigTestShowDetails = x46' @@ -708,7 +714,7 @@ instance Arbitrary PackageConfig where (x30', x31', x32', (x33', x33_1'), x34'), (x35', x36', x37', x38', x43', x39'), (x40', x41'), - (x44', x45', x46', x47', x48', x49', x51', x52'))) + (x44', x45', x46', x47', x48', x49', x51', x52', x54', x55'))) <- shrink (((preShrink_Paths x00, preShrink_Args x01, x02, x03, x04), (x05, x42, x06, x50, x07, x08, x09), @@ -722,7 +728,7 @@ instance Arbitrary PackageConfig where (x30, x31, x32, (x33, x33_1), x34), (x35, x36, fmap NonEmpty x37, x38, x43, fmap NonEmpty x39), (x40, x41), - (x44, x45, x46, x47, x48, x49, x51, x52))) + (x44, x45, x46, x47, x48, x49, x51, x52, x54, x55))) ] where preShrink_Paths = Map.map NonEmpty From 5737f1104b556e382d43b9abad224b37acdb4034 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 06:40:59 +0200 Subject: [PATCH 03/19] Added HaddockProjectFlags This is useful for passing arguments to `haddock-project` command which will create haddocks for all the components, together with a consistent index. --- Cabal/src/Distribution/Simple/Setup.hs | 165 ++++++++++++++++++++++++- 1 file changed, 164 insertions(+), 1 deletion(-) diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index b15a444e3d1..d0ceb6c8be0 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -43,6 +43,8 @@ module Distribution.Simple.Setup ( InstallFlags(..), emptyInstallFlags, defaultInstallFlags, installCommand, HaddockTarget(..), HaddockFlags(..), emptyHaddockFlags, defaultHaddockFlags, haddockCommand, + HaddockProjectFlags(..), emptyHaddockProjectFlags, + defaultHaddockProjectFlags, haddockProjectCommand, HscolourFlags(..), emptyHscolourFlags, defaultHscolourFlags, hscolourCommand, BuildFlags(..), emptyBuildFlags, defaultBuildFlags, buildCommand, DumpBuildInfo(..), @@ -58,7 +60,7 @@ module Distribution.Simple.Setup ( defaultBenchmarkFlags, benchmarkCommand, CopyDest(..), configureArgs, configureOptions, configureCCompiler, configureLinker, - buildOptions, haddockOptions, installDirsOptions, + buildOptions, haddockOptions, haddockProjectOptions, installDirsOptions, testOptions', benchmarkOptions', programDbOptions, programDbPaths', programFlagsDescription, @@ -1561,6 +1563,167 @@ instance Monoid HaddockFlags where instance Semigroup HaddockFlags where (<>) = gmappend +-- ------------------------------------------------------------ +-- * HaddocksFlags flags +-- ------------------------------------------------------------ + +data HaddockProjectFlags = HaddockProjectFlags { + -- options passed to @haddock@ via 'createHaddockIndex' + haddockProjectDir :: Flag String, + -- ^ output directory of combined haddockProject, the default is './haddocks' + haddockProjectPrologue :: Flag String, + haddockProjectGenIndex :: Flag Bool, + haddockProjectGenContents :: Flag Bool, + haddockProjectInterfaces :: Flag [(FilePath, Maybe FilePath, Maybe FilePath)], + -- ^ 'haddockProjectInterfaces' is inferred by the 'haddocksAction'; currently not + -- exposed to the user. + + -- options passed to @haddock@ via 'HaddockFlags' when building + -- documentation + + -- haddockHtml is not supported + -- haddockForHackage is not supported + haddockProjectExecutables :: Flag Bool, + haddockProjectTestSuites :: Flag Bool, + haddockProjectBenchmarks :: Flag Bool, + haddockProjectForeignLibs :: Flag Bool, + haddockProjectInternal :: Flag Bool, + haddockProjectCss :: Flag FilePath, + haddockProjectLinkedSource :: Flag Bool, + haddockProjectQuickJump :: Flag Bool, + haddockProjectHscolourCss :: Flag FilePath, + -- haddockProjectContent is not supported, a fixed value is provided + -- haddockProjectIndex is not supported, a fixed value is provided + -- haddockDistPerf is not supported, note: it changes location of the haddockProject + haddockProjectKeepTempFiles:: Flag Bool, + haddockProjectVerbosity :: Flag Verbosity + -- haddockBaseUrl is not supported, a fixed value is provided + } + deriving (Show, Generic, Typeable) + +defaultHaddockProjectFlags :: HaddockProjectFlags +defaultHaddockProjectFlags = HaddockProjectFlags { + haddockProjectDir = Flag "./haddocks", + haddockProjectPrologue = NoFlag, + haddockProjectGenIndex = Flag False, + haddockProjectGenContents = Flag False, + haddockProjectTestSuites = Flag False, + haddockProjectExecutables = Flag False, + haddockProjectBenchmarks = Flag False, + haddockProjectForeignLibs = Flag False, + haddockProjectInternal = Flag False, + haddockProjectCss = NoFlag, + haddockProjectLinkedSource = Flag False, + haddockProjectQuickJump = Flag False, + haddockProjectHscolourCss = NoFlag, + haddockProjectKeepTempFiles= Flag False, + haddockProjectVerbosity = Flag normal, + haddockProjectInterfaces = NoFlag + } + +haddockProjectCommand :: CommandUI HaddockProjectFlags +haddockProjectCommand = CommandUI + { commandName = "v2-haddock-project" + , commandSynopsis = "Generate Haddocks HTML documentation for the cabal project." + , commandDescription = Just $ \_ -> + "Require the programm haddock, version 2.26.\n" + , commandNotes = Nothing + , commandUsage = usageAlternatives "haddocks" $ + [ "[FLAGS]" + , "COMPONENTS [FLAGS]" + ] + , commandDefaultFlags = defaultHaddockProjectFlags + , commandOptions = haddockProjectOptions + } + +haddockProjectOptions :: ShowOrParseArgs -> [OptionField HaddockProjectFlags] +haddockProjectOptions _showOrParseArgs = + [option "" ["output"] + "Output directory" + haddockProjectDir (\v flags -> flags { haddockProjectDir = v }) + (optArg' "DIRECTORY" maybeToFlag (fmap Just . flagToList)) + + ,option "" ["prologue"] + "File path to a prologue file in haddock format" + haddockProjectPrologue (\v flags -> flags { haddockProjectPrologue = v}) + (optArg' "PATH" maybeToFlag (fmap Just . flagToList)) + + ,option "" ["gen-index"] + "Generate index" + haddockProjectGenIndex (\v flags -> flags { haddockProjectGenIndex = v}) + trueArg + + ,option "" ["gen-contents"] + "Generate contents" + haddockProjectGenContents (\v flags -> flags { haddockProjectGenContents = v}) + trueArg + + ,option "" ["executables"] + "Run haddock for Executables targets" + haddockProjectExecutables (\v flags -> flags { haddockProjectExecutables = v }) + trueArg + + ,option "" ["tests"] + "Run haddock for Test Suite targets" + haddockProjectTestSuites (\v flags -> flags { haddockProjectTestSuites = v }) + trueArg + + ,option "" ["benchmarks"] + "Run haddock for Benchmark targets" + haddockProjectBenchmarks (\v flags -> flags { haddockProjectBenchmarks = v }) + trueArg + + ,option "" ["foreign-libraries"] + "Run haddock for Foreign Library targets" + haddockProjectForeignLibs (\v flags -> flags { haddockProjectForeignLibs = v }) + trueArg + + ,option "" ["internal"] + "Run haddock for internal modules and include all symbols" + haddockProjectInternal (\v flags -> flags { haddockProjectInternal = v }) + trueArg + + ,option "" ["css"] + "Use PATH as the haddock stylesheet" + haddockProjectCss (\v flags -> flags { haddockProjectCss = v }) + (reqArgFlag "PATH") + + ,option "" ["hyperlink-source","hyperlink-sources","hyperlinked-source"] + "Hyperlink the documentation to the source code" + haddockProjectLinkedSource (\v flags -> flags { haddockProjectLinkedSource = v }) + trueArg + + ,option "" ["quickjump"] + "Generate an index for interactive documentation navigation" + haddockProjectQuickJump (\v flags -> flags { haddockProjectQuickJump = v }) + trueArg + + ,option "" ["hscolour-css"] + "Use PATH as the HsColour stylesheet" + haddockProjectHscolourCss (\v flags -> flags { haddockProjectHscolourCss = v }) + (reqArgFlag "PATH") + + ,option "" ["keep-temp-files"] + "Keep temporary files" + haddockProjectKeepTempFiles (\b flags -> flags { haddockProjectKeepTempFiles = b }) + trueArg + + ,optionVerbosity haddockProjectVerbosity + (\v flags -> flags { haddockProjectVerbosity = v }) + + ] + + +emptyHaddockProjectFlags :: HaddockProjectFlags +emptyHaddockProjectFlags = mempty + +instance Monoid HaddockProjectFlags where + mempty = gmempty + mappend = (<>) + +instance Semigroup HaddockProjectFlags where + (<>) = gmappend + -- ------------------------------------------------------------ -- * Clean flags -- ------------------------------------------------------------ From 6d8adf13101c4d28fef14bdec55d485feec356fd Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 08:18:58 +0200 Subject: [PATCH 04/19] Relaxed preconditions of parsePureArgs and renderArgs We need 'renderArgs' to work when we create an index. In this case some of the options will not be set. --- Cabal/src/Distribution/Simple/Haddock.hs | 35 ++++++++++++++---------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index 4b2e2f29e9f..a49c9cc0040 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -624,7 +624,9 @@ renderArgs verbosity tmpFileOpts version comp platform args k = do case o of Html -> "index.html" Hoogle -> pkgstr <.> "txt") - $ arg argOutput + . fromFlagOrDefault [Html] + . argOutput + $ args where pkgstr = prettyShow $ packageName pkgid pkgid = arg argPackageName @@ -632,23 +634,23 @@ renderArgs verbosity tmpFileOpts version comp platform args k = do renderPureArgs :: Version -> Compiler -> Platform -> HaddockArgs -> [String] renderPureArgs version comp platform args = concat - [ (:[]) . (\f -> "--dump-interface="++ unDir (argOutputDir args) f) - . fromFlag . argInterfaceFile $ args + [ map (\f -> "--dump-interface="++ unDir (argOutputDir args) f) + . flagToList . argInterfaceFile $ args , if isVersion 2 16 - then (\pkg -> [ "--package-name=" ++ prettyShow (pkgName pkg) - , "--package-version=" ++ prettyShow (pkgVersion pkg) - ]) - . fromFlag . argPackageName $ args + then maybe [] (\pkg -> [ "--package-name=" ++ prettyShow (pkgName pkg) + , "--package-version=" ++ prettyShow (pkgVersion pkg) + ]) + . flagToMaybe . argPackageName $ args else [] , [ "--since-qual=external" | isVersion 2 20 ] , [ "--quickjump" | isVersion 2 19 - , fromFlag . argQuickJump $ args ] + , _ <- flagToList . argQuickJump $ args ] , [ "--hyperlinked-source" | isVersion 2 17 - , fromFlag . argLinkedSource $ args ] + , True <- flagToList . argLinkedSource $ args ] , (\(All b,xs) -> bool (map (("--hide=" ++) . prettyShow) xs) [] b) . argHideModules $ args @@ -673,16 +675,19 @@ renderPureArgs version comp platform args = concat , bool [] [verbosityFlag] . getAny . argVerbose $ args , map (\o -> case o of Hoogle -> "--hoogle"; Html -> "--html") - . fromFlag . argOutput $ args + . fromFlagOrDefault [] . argOutput $ args , renderInterfaces . argInterfaces $ args , (:[]) . ("--odir="++) . unDir . argOutputDir $ args - , (:[]) . ("--title="++) - . (bool (++" (internal documentation)") - id (getAny $ argIgnoreExports args)) - . fromFlag . argTitle $ args + , maybe [] + ( (:[]) + . ("--title="++) + . (bool (++" (internal documentation)") + id (getAny $ argIgnoreExports args)) + ) + . flagToMaybe . argTitle $ args , [ "--optghc=" ++ opt | let opts = argGhcOptions args , opt <- renderGhcOptions comp platform opts ] @@ -710,7 +715,7 @@ renderPureArgs version comp platform args = concat -- enabled , Just x <- [hypsrc] , isVersion 2 17 - , fromFlag . argLinkedSource $ args + , fromFlagOrDefault False . argLinkedSource $ args ] , [ i ] ]) From 396c354780a3aefb859d7cc3089e96cba039f128 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 08:21:17 +0200 Subject: [PATCH 05/19] Extended HaddocksArgs Added arguments: * 'argGenContents': haddocks' '--gen-contents' * 'argGenIndex': haddocks' '--gen-index' * 'argPrologueFile': haddocks' '--prologue' but unlike '--argPrlogue' it passes the file name not the prologue text itself. --- Cabal/src/Distribution/Simple/Haddock.hs | 84 ++++++++++++++++-------- 1 file changed, 58 insertions(+), 26 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index a49c9cc0040..da1b684ca1b 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -105,8 +105,12 @@ data HaddockArgs = HaddockArgs { -- ^ Optional custom CSS file. argContents :: Flag String, -- ^ Optional URL to contents page. + argGenContents :: Flag Bool, + -- ^ Generate contents argIndex :: Flag String, -- ^ Optional URL to index page. + argGenIndex :: Flag Bool, + -- ^ Generate index argBaseUrl :: Flag String, -- ^ Optional base url from which static files will be loaded. argVerbose :: Any, @@ -119,7 +123,9 @@ data HaddockArgs = HaddockArgs { argTitle :: Flag String, -- ^ Page title, required. argPrologue :: Flag String, - -- ^ Prologue text, required. + -- ^ Prologue text, required for 'haddock', ignored by 'haddocks'. + argPrologueFile :: Flag FilePath, + -- ^ Prologue file name, ignored by 'haddock', optional for 'haddocks'. argGhcOptions :: GhcOptions, -- ^ Additional flags to pass to GHC. argGhcLibDir :: Flag FilePath, @@ -280,7 +286,7 @@ haddock pkg_descr lbi suffixes flags' = do version exe let exeArgs' = commonArgs `mappend` exeArgs runHaddock verbosity tmpFileOpts comp platform - haddockProg exeArgs' + haddockProg True exeArgs' Nothing -> do warn (fromFlag $ haddockVerbosity flags) "Unsupported component, skipping..." @@ -299,7 +305,7 @@ haddock pkg_descr lbi suffixes flags' = do libArgs <- fromLibrary verbosity tmp lbi' clbi htmlTemplate version lib let libArgs' = commonArgs `mappend` libArgs - runHaddock verbosity tmpFileOpts comp platform haddockProg libArgs' + runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs' pwd <- getCurrentDirectory @@ -326,7 +332,7 @@ haddock pkg_descr lbi suffixes flags' = do flibArgs <- fromForeignLib verbosity tmp lbi' clbi htmlTemplate version flib let libArgs' = commonArgs `mappend` flibArgs - runHaddock verbosity tmpFileOpts comp platform haddockProg libArgs') + runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs') >> return index @@ -356,8 +362,10 @@ fromFlags env flags = argCssFile = haddockCss flags, argContents = fmap (fromPathTemplate . substPathTemplate env) (haddockContents flags), + argGenContents = Flag False, argIndex = fmap (fromPathTemplate . substPathTemplate env) (haddockIndex flags), + argGenIndex = Flag False, argBaseUrl = haddockBaseUrl flags, argVerbose = maybe mempty (Any . (>= deafening)) . flagToMaybe $ haddockVerbosity flags, @@ -568,10 +576,11 @@ runHaddock :: Verbosity -> Compiler -> Platform -> ConfiguredProgram + -> Bool -- ^ require targets -> HaddockArgs -> IO () -runHaddock verbosity tmpFileOpts comp platform haddockProg args - | null (argTargets args) = warn verbosity $ +runHaddock verbosity tmpFileOpts comp platform haddockProg requireTargets args + | requireTargets && null (argTargets args) = warn verbosity $ "Haddocks are being requested, but there aren't any modules given " ++ "to create documentation for." | otherwise = do @@ -597,26 +606,45 @@ renderArgs verbosity tmpFileOpts version comp platform args k = do let haddockSupportsUTF8 = version >= mkVersion [2,14,4] haddockSupportsResponseFiles = version > mkVersion [2,16,2] createDirectoryIfMissingVerbose verbosity True outputDir - withTempFileEx tmpFileOpts outputDir "haddock-prologue.txt" $ - \prologueFileName h -> do - do - when haddockSupportsUTF8 (hSetEncoding h utf8) - hPutStrLn h $ fromFlag $ argPrologue args - hClose h - let pflag = "--prologue=" ++ prologueFileName - renderedArgs = pflag : renderPureArgs version comp platform args - if haddockSupportsResponseFiles - then - withResponseFile - verbosity - tmpFileOpts - outputDir - "haddock-response.txt" - (if haddockSupportsUTF8 then Just utf8 else Nothing) - renderedArgs - (\responseFileName -> k (["@" ++ responseFileName], result)) - else - k (renderedArgs, result) + case argPrologue args of + Flag prologueText -> + withTempFileEx tmpFileOpts outputDir "haddock-prologue.txt" $ + \prologueFileName h -> do + do + when haddockSupportsUTF8 (hSetEncoding h utf8) + hPutStrLn h prologueText + hClose h + let pflag = "--prologue=" ++ prologueFileName + renderedArgs = pflag : renderPureArgs version comp platform args + if haddockSupportsResponseFiles + then + withResponseFile + verbosity + tmpFileOpts + outputDir + "haddock-response.txt" + (if haddockSupportsUTF8 then Just utf8 else Nothing) + renderedArgs + (\responseFileName -> k (["@" ++ responseFileName], result)) + else + k (renderedArgs, result) + _ -> do + let renderedArgs = (case argPrologueFile args of + Flag pfile -> ["--prologue="++pfile] + _ -> []) + <> renderPureArgs version comp platform args + if haddockSupportsResponseFiles + then + withResponseFile + verbosity + tmpFileOpts + outputDir + "haddock-response.txt" + (if haddockSupportsUTF8 then Just utf8 else Nothing) + renderedArgs + (\responseFileName -> k (["@" ++ responseFileName], result)) + else + k (renderedArgs, result) where outputDir = (unDir $ argOutputDir args) result = intercalate ", " @@ -668,8 +696,12 @@ renderPureArgs version comp platform args = concat , maybe [] ((:[]) . ("--use-contents="++)) . flagToMaybe . argContents $ args + , bool ["--gen-contents"] [] .fromFlagOrDefault False . argGenContents $ args + , maybe [] ((:[]) . ("--use-index="++)) . flagToMaybe . argIndex $ args + , bool ["--gen-index"] [] . fromFlagOrDefault False . argGenIndex $ args + , maybe [] ((:[]) . ("--base-url="++)) . flagToMaybe . argBaseUrl $ args , bool [] [verbosityFlag] . getAny . argVerbose $ args From e01c9f121f2c456614c0c61ebd3e4028597d426c Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 08:23:07 +0200 Subject: [PATCH 06/19] Added createHaddockIndex --- Cabal/src/Distribution/Simple/Haddock.hs | 31 +++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index da1b684ca1b..c9713b192c4 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -20,7 +20,7 @@ -- source, with coloured syntax highlighting. module Distribution.Simple.Haddock ( - haddock, hscolour, + haddock, createHaddockIndex, hscolour, haddockPackagePaths ) where @@ -344,6 +344,22 @@ haddock pkg_descr lbi suffixes flags' = do files <- matchDirFileGlob verbosity (specVersion pkg_descr) "." fpath for_ files $ copyFileTo verbosity (unDir $ argOutputDir commonArgs) + +-- | Execute 'Haddock' configured with 'HaddocksFlags'. It is used to build +-- index and contents for documentation of multiple packages. +-- +createHaddockIndex :: Verbosity + -> ProgramDb + -> Compiler + -> Platform + -> HaddockProjectFlags + -> IO () +createHaddockIndex verbosity programDb comp platform flags = do + let args = fromHaddockProjectFlags flags + (haddockProg, _version) <- + getHaddockProg verbosity programDb comp args (haddockProjectQuickJump flags) + runHaddock verbosity defaultTempFileOptions comp platform haddockProg False args + -- ------------------------------------------------------------------------------ -- Contributions to HaddockArgs (see also Doctest.hs for very similar code). @@ -381,6 +397,19 @@ fromFlags env flags = where ghcArgs = fromMaybe [] . lookup "ghc" . haddockProgramArgs $ flags +fromHaddockProjectFlags :: HaddockProjectFlags -> HaddockArgs +fromHaddockProjectFlags flags = + mempty + { argOutputDir = Dir (fromFlag $ haddockProjectDir flags) + , argQuickJump = haddockProjectQuickJump flags + , argGenContents = haddockProjectGenContents flags + , argGenIndex = haddockProjectGenIndex flags + , argPrologueFile = haddockProjectPrologue flags + , argInterfaces = fromFlagOrDefault [] (haddockProjectInterfaces flags) + , argLinkedSource = haddockProjectLinkedSource flags + } + + fromPackageDescription :: HaddockTarget -> PackageDescription -> HaddockArgs fromPackageDescription haddockTarget pkg_descr = mempty { argInterfaceFile = Flag $ haddockName pkg_descr From b3291639c405f1f0c7e5cf7f3d34cfd1bee47fa4 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 06:42:44 +0200 Subject: [PATCH 07/19] Added haddock-project command The 'haddock-project' command can be used to create haddocks of all components together with indexes (html, quickjump) and the content page. --- cabal-install/cabal-install.cabal | 1 + cabal-install/main/Main.hs | 3 + .../Distribution/Client/CmdHaddockProject.hs | 206 ++++++++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 cabal-install/src/Distribution/Client/CmdHaddockProject.hs diff --git a/cabal-install/cabal-install.cabal b/cabal-install/cabal-install.cabal index 235956d2886..21905db3d52 100644 --- a/cabal-install/cabal-install.cabal +++ b/cabal-install/cabal-install.cabal @@ -83,6 +83,7 @@ library Distribution.Client.CmdExec Distribution.Client.CmdFreeze Distribution.Client.CmdHaddock + Distribution.Client.CmdHaddockProject Distribution.Client.CmdInstall Distribution.Client.CmdInstall.ClientInstallFlags Distribution.Client.CmdInstall.ClientInstallTargetSelector diff --git a/cabal-install/main/Main.hs b/cabal-install/main/Main.hs index 6e65f7bab9e..8395651e6c9 100644 --- a/cabal-install/main/Main.hs +++ b/cabal-install/main/Main.hs @@ -78,6 +78,7 @@ import qualified Distribution.Client.CmdBuild as CmdBuild import qualified Distribution.Client.CmdRepl as CmdRepl import qualified Distribution.Client.CmdFreeze as CmdFreeze import qualified Distribution.Client.CmdHaddock as CmdHaddock +import qualified Distribution.Client.CmdHaddockProject as CmdHaddockProject import qualified Distribution.Client.CmdInstall as CmdInstall import qualified Distribution.Client.CmdRun as CmdRun import qualified Distribution.Client.CmdTest as CmdTest @@ -257,6 +258,8 @@ mainWorker args = do , newCmd CmdRepl.replCommand CmdRepl.replAction , newCmd CmdFreeze.freezeCommand CmdFreeze.freezeAction , newCmd CmdHaddock.haddockCommand CmdHaddock.haddockAction + , newCmd CmdHaddockProject.haddockProjectCommand + CmdHaddockProject.haddockProjectAction , newCmd CmdInstall.installCommand CmdInstall.installAction , newCmd CmdRun.runCommand CmdRun.runAction , newCmd CmdTest.testCommand CmdTest.testAction diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs new file mode 100644 index 00000000000..6ec59b7a70c --- /dev/null +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -0,0 +1,206 @@ +module Distribution.Client.CmdHaddockProject + ( haddockProjectCommand + , haddockProjectAction + ) where + +import Prelude () +import Distribution.Client.Compat.Prelude hiding (get) + +import qualified Distribution.Client.CmdBuild as CmdBuild +import qualified Distribution.Client.CmdHaddock as CmdHaddock + +import Distribution.Client.DistDirLayout (DistDirLayout(..) + ,CabalDirLayout(..) + ,StoreDirLayout(..)) +import Distribution.Client.InstallPlan (foldPlanPackage) +import qualified Distribution.Client.InstallPlan as InstallPlan +import qualified Distribution.Client.NixStyleOptions as NixStyleOptions +import Distribution.Client.ProjectOrchestration + (AvailableTarget(..) + ,AvailableTargetStatus(..) + ,ProjectBaseContext(..) + ,ProjectBuildContext(..) + ,TargetSelector(..) + ,printPlan + ,pruneInstallPlanToTargets + ,resolveTargets + ,runProjectPreBuildPhase + ,selectComponentTargetBasic) +import Distribution.Client.ProjectPlanning (ElaboratedConfiguredPackage(..) + ,ElaboratedInstallPlan + ,ElaboratedSharedConfig(..) + ,TargetAction(..)) +import Distribution.Client.ProjectPlanning.Types + (elabDistDirParams) +import Distribution.Client.Setup (GlobalFlags(..) + ,ConfigFlags(..)) +import Distribution.Client.ScriptUtils (AcceptNoTargets(..) + ,TargetContext(..) + ,updateContextAndWriteProjectFile + ,withContextAndSelectors) +import Distribution.Client.TargetProblem (TargetProblem(..)) + +import Distribution.Types.PackageId (pkgName) +import Distribution.Types.PackageName (unPackageName) +import Distribution.Simple.Command + ( CommandUI(..) ) +import Distribution.Simple.Compiler + ( Compiler (..) ) +import Distribution.Simple.InstallDirs + ( toPathTemplate ) +import Distribution.Simple.Haddock (createHaddockIndex) +import Distribution.Simple.Utils + ( die', createDirectoryIfMissingVerbose + , copyDirectoryRecursive, ) +import Distribution.Simple.Setup + ( HaddockFlags(..), defaultHaddockFlags + , HaddockProjectFlags(..) + , Flag(..), fromFlag, fromFlagOrDefault + , haddockProjectCommand + ) +import Distribution.Verbosity as Verbosity + ( normal ) + +import System.FilePath ( normalise, (), (<.>) ) +import System.Directory ( doesDirectoryExist ) + +haddockProjectAction :: HaddockProjectFlags -> [String] -> GlobalFlags -> IO () +haddockProjectAction flags _extraArgs globalFlags = do + -- create destination directory if it does not exist + let outputDir = normalise $ fromFlag (haddockProjectDir flags) + createDirectoryIfMissingVerbose verbosity True outputDir + + -- build all packages with appropriate haddock flags + let haddockFlags = defaultHaddockFlags + { haddockHtml = Flag True + , haddockBaseUrl = Flag ".." + , haddockExecutables = haddockProjectExecutables flags + , haddockTestSuites = haddockProjectTestSuites flags + , haddockBenchmarks = haddockProjectBenchmarks flags + , haddockForeignLibs = haddockProjectForeignLibs flags + , haddockInternal = haddockProjectInternal flags + , haddockCss = haddockProjectCss flags + , haddockLinkedSource = haddockProjectLinkedSource flags + , haddockQuickJump = haddockProjectQuickJump flags + , haddockHscolourCss = haddockProjectHscolourCss flags + , haddockContents = Flag (toPathTemplate "../index.html") + , haddockIndex = Flag (toPathTemplate "../doc-index.html") + , haddockKeepTempFiles= haddockProjectKeepTempFiles flags + , haddockVerbosity = haddockProjectVerbosity flags + } + nixFlags = (commandDefaultFlags CmdHaddock.haddockCommand) + { NixStyleOptions.haddockFlags = haddockFlags + , NixStyleOptions.configFlags = + (NixStyleOptions.configFlags (commandDefaultFlags CmdBuild.buildCommand)) + { configVerbosity = haddockProjectVerbosity flags } + } + CmdHaddock.haddockAction + nixFlags + ["all"] + globalFlags + + -- copy local packages to the destination directory + withContextAndSelectors RejectNoTargets Nothing nixFlags ["all"] globalFlags $ \targetCtx ctx targetSelectors -> do + baseCtx <- case targetCtx of + ProjectContext -> return ctx + GlobalContext -> return ctx + ScriptContext path exemeta -> updateContextAndWriteProjectFile ctx path exemeta + let distLayout = distDirLayout baseCtx + cabalLayout = cabalDirLayout baseCtx + buildCtx <- + runProjectPreBuildPhase verbosity baseCtx $ \elaboratedPlan -> do + -- Interpret the targets on the command line as build targets + -- (as opposed to say repl or haddock targets). + targets <- either reportTargetProblems return + $ resolveTargets + selectPackageTargets + selectComponentTargetBasic + elaboratedPlan + Nothing + targetSelectors + + let elaboratedPlan' = pruneInstallPlanToTargets + TargetActionBuild + targets + elaboratedPlan + return (elaboratedPlan', targets) + + printPlan verbosity baseCtx buildCtx + + let elaboratedPlan :: ElaboratedInstallPlan + elaboratedPlan = elaboratedPlanOriginal buildCtx + + sharedConfig :: ElaboratedSharedConfig + sharedConfig = elaboratedShared buildCtx + + pkgs :: [ElaboratedConfiguredPackage] + pkgs = matchingPackages elaboratedPlan + packageNames <- fmap (nub . catMaybes) $ for pkgs $ \package -> + if elabLocalToProject package + then do + let distDirParams = elabDistDirParams sharedConfig package + buildDir = distBuildDirectory distLayout distDirParams + packageName = unPackageName (pkgName $ elabPkgSourceId package) + let docDir = buildDir + "doc" "html" + packageName + destDir = outputDir packageName + a <- doesDirectoryExist docDir + case a of + True -> copyDirectoryRecursive verbosity docDir destDir + >> return (Just (packageName, destDir)) + False -> return Nothing + else do + let packageName = unPackageName (pkgName $ elabPkgSourceId package) + packageDir = storePackageDirectory (cabalStoreDirLayout cabalLayout) + (compilerId (pkgConfigCompiler sharedConfig)) + (elabUnitId package) + docDir = packageDir "share" "doc" "html" + destDir = outputDir packageName + a <- doesDirectoryExist docDir + case a of + True -> copyDirectoryRecursive verbosity docDir destDir + >> return (Just (packageName, destDir)) + False -> return Nothing + + -- run haddock to generate index, content, etc. + let flags' = flags + { haddockProjectDir = Flag outputDir + , haddockProjectInterfaces = Flag + [ ( destDir packageName <.> "haddock" + , Just packageName + , Just packageName + ) + | (packageName, destDir) <- packageNames + ] + } + createHaddockIndex verbosity + (pkgConfigCompilerProgs sharedConfig) + (pkgConfigCompiler sharedConfig) + (pkgConfigPlatform sharedConfig) + flags' + where + verbosity = fromFlagOrDefault normal (haddockProjectVerbosity flags) + + reportTargetProblems :: Show x => [x] -> IO a + reportTargetProblems = + die' verbosity . unlines . map show + + -- TODO: this is just a sketch + selectPackageTargets :: TargetSelector + -> [AvailableTarget k] + -> Either (TargetProblem ()) [k] + selectPackageTargets _ ts = Right $ + mapMaybe + (\t -> case availableTargetStatus t of + TargetBuildable k _ | availableTargetLocalToProject t + -> Just k + _ -> Nothing) + ts + + matchingPackages :: ElaboratedInstallPlan + -> [ElaboratedConfiguredPackage] + matchingPackages = + catMaybes + . fmap (foldPlanPackage (const Nothing) Just) + . InstallPlan.toList From 7564f50297346d821e6dffdb2f3fdddc33eb0cee Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 20:31:28 +0200 Subject: [PATCH 08/19] Added support for --haddock-lib option of the haddock-project command This allows to test against a newer version of haddock than one that comes with `ghc`, even with head of `haddock` repository. --- Cabal/src/Distribution/Simple/Haddock.hs | 7 ++++++- Cabal/src/Distribution/Simple/Setup.hs | 21 +++++++++++++++---- .../Distribution/Client/CmdHaddockProject.hs | 1 + .../src/Distribution/Client/Config.hs | 1 + .../src/Distribution/Client/PackageHash.hs | 4 +++- .../Client/ProjectConfig/Legacy.hs | 5 ++++- .../Client/ProjectConfig/Types.hs | 1 + .../Distribution/Client/ProjectPlanning.hs | 5 ++++- .../Client/ProjectPlanning/Types.hs | 1 + .../src/Distribution/Client/Setup.hs | 2 +- .../Distribution/Client/ProjectConfig.hs | 8 +++++-- 11 files changed, 45 insertions(+), 11 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index c9713b192c4..4d7dab68846 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -132,8 +132,10 @@ data HaddockArgs = HaddockArgs { -- ^ To find the correct GHC, required. argReexports :: [OpenModule], -- ^ Re-exported modules - argTargets :: [FilePath] + argTargets :: [FilePath], -- ^ Modules to process. + argLib :: Flag String + -- ^ haddock's static \/ auxiliary files. } deriving Generic -- | The FilePath of a directory, it's a monoid under '()'. @@ -383,6 +385,7 @@ fromFlags env flags = (haddockIndex flags), argGenIndex = Flag False, argBaseUrl = haddockBaseUrl flags, + argLib = haddockLib flags, argVerbose = maybe mempty (Any . (>= deafening)) . flagToMaybe $ haddockVerbosity flags, argOutput = @@ -407,6 +410,7 @@ fromHaddockProjectFlags flags = , argPrologueFile = haddockProjectPrologue flags , argInterfaces = fromFlagOrDefault [] (haddockProjectInterfaces flags) , argLinkedSource = haddockProjectLinkedSource flags + , argLib = haddockProjectLib flags } @@ -763,6 +767,7 @@ renderPureArgs version comp platform args = concat ] , argTargets $ args + , maybe [] ((:[]) . ("--lib="++)) . flagToMaybe . argLib $ args ] where renderInterfaces = map renderInterface diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index d0ceb6c8be0..463d213d7c8 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -1384,6 +1384,7 @@ data HaddockFlags = HaddockFlags { haddockVerbosity :: Flag Verbosity, haddockCabalFilePath :: Flag FilePath, haddockBaseUrl :: Flag String, + haddockLib :: Flag String, haddockArgs :: [String] } deriving (Show, Generic, Typeable) @@ -1412,6 +1413,7 @@ defaultHaddockFlags = HaddockFlags { haddockCabalFilePath = mempty, haddockIndex = NoFlag, haddockBaseUrl = NoFlag, + haddockLib = NoFlag, haddockArgs = mempty } @@ -1551,6 +1553,11 @@ haddockOptions showOrParseArgs = "Base URL for static files." haddockBaseUrl (\v flags -> flags { haddockBaseUrl = v}) (reqArgFlag "URL") + + ,option "" ["lib"] + "location of Haddocks static / auxiliary files" + haddockLib (\v flags -> flags { haddockLib = v}) + (reqArgFlag "DIR") ] emptyHaddockFlags :: HaddockFlags @@ -1592,12 +1599,13 @@ data HaddockProjectFlags = HaddockProjectFlags { haddockProjectLinkedSource :: Flag Bool, haddockProjectQuickJump :: Flag Bool, haddockProjectHscolourCss :: Flag FilePath, - -- haddockProjectContent is not supported, a fixed value is provided - -- haddockProjectIndex is not supported, a fixed value is provided - -- haddockDistPerf is not supported, note: it changes location of the haddockProject + -- haddockContent is not supported, a fixed value is provided + -- haddockIndex is not supported, a fixed value is provided + -- haddockDistPerf is not supported, note: it changes location of the haddocks haddockProjectKeepTempFiles:: Flag Bool, - haddockProjectVerbosity :: Flag Verbosity + haddockProjectVerbosity :: Flag Verbosity, -- haddockBaseUrl is not supported, a fixed value is provided + haddockProjectLib :: Flag String } deriving (Show, Generic, Typeable) @@ -1618,6 +1626,7 @@ defaultHaddockProjectFlags = HaddockProjectFlags { haddockProjectHscolourCss = NoFlag, haddockProjectKeepTempFiles= Flag False, haddockProjectVerbosity = Flag normal, + haddockProjectLib = NoFlag, haddockProjectInterfaces = NoFlag } @@ -1711,6 +1720,10 @@ haddockProjectOptions _showOrParseArgs = ,optionVerbosity haddockProjectVerbosity (\v flags -> flags { haddockProjectVerbosity = v }) + ,option "" ["lib"] + "location of Haddocks static / auxiliary files" + haddockProjectLib (\v flags -> flags { haddockProjectLib = v}) + (reqArgFlag "DIR") ] diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 6ec59b7a70c..16bbc72e8a1 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -87,6 +87,7 @@ haddockProjectAction flags _extraArgs globalFlags = do , haddockIndex = Flag (toPathTemplate "../doc-index.html") , haddockKeepTempFiles= haddockProjectKeepTempFiles flags , haddockVerbosity = haddockProjectVerbosity flags + , haddockLib = haddockProjectLib flags } nixFlags = (commandDefaultFlags CmdHaddock.haddockCommand) { NixStyleOptions.haddockFlags = haddockFlags diff --git a/cabal-install/src/Distribution/Client/Config.hs b/cabal-install/src/Distribution/Client/Config.hs index ce989e0cf50..7d7e4836fa0 100644 --- a/cabal-install/src/Distribution/Client/Config.hs +++ b/cabal-install/src/Distribution/Client/Config.hs @@ -489,6 +489,7 @@ instance Semigroup SavedConfig where haddockCabalFilePath = combine haddockCabalFilePath, haddockIndex = combine haddockIndex, haddockBaseUrl = combine haddockBaseUrl, + haddockLib = combine haddockLib, haddockArgs = lastNonEmpty haddockArgs } where diff --git a/cabal-install/src/Distribution/Client/PackageHash.hs b/cabal-install/src/Distribution/Client/PackageHash.hs index 0ec31101a48..067027db541 100644 --- a/cabal-install/src/Distribution/Client/PackageHash.hs +++ b/cabal-install/src/Distribution/Client/PackageHash.hs @@ -217,7 +217,8 @@ data PackageHashConfigInputs = PackageHashConfigInputs { pkgHashHaddockQuickJump :: Bool, pkgHashHaddockContents :: Maybe PathTemplate, pkgHashHaddockIndex :: Maybe PathTemplate, - pkgHashHaddockBaseUrl :: Maybe String + pkgHashHaddockBaseUrl :: Maybe String, + pkgHashHaddockLib :: Maybe String -- TODO: [required eventually] pkgHashToolsVersions ? -- TODO: [required eventually] pkgHashToolsExtraOptions ? @@ -313,6 +314,7 @@ renderPackageHashInputs PackageHashInputs{ , opt "haddock-contents-location" Nothing (maybe "" fromPathTemplate) pkgHashHaddockContents , opt "haddock-index-location" Nothing (maybe "" fromPathTemplate) pkgHashHaddockIndex , opt "haddock-base-url" Nothing (fromMaybe "") pkgHashHaddockBaseUrl + , opt "haddock-lib" Nothing (fromMaybe "") pkgHashHaddockLib ] ++ Map.foldrWithKey (\prog args acc -> opt (prog ++ "-options") [] unwords args : acc) [] pkgHashProgramArgs where diff --git a/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs b/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs index ac0a9ec918c..76eb925fa57 100644 --- a/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs +++ b/cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs @@ -597,7 +597,8 @@ convertLegacyPerPackageFlags configFlags installFlags haddockHscolourCss = packageConfigHaddockHscolourCss, haddockContents = packageConfigHaddockContents, haddockIndex = packageConfigHaddockIndex, - haddockBaseUrl = packageConfigHaddockBaseUrl + haddockBaseUrl = packageConfigHaddockBaseUrl, + haddockLib = packageConfigHaddockLib } = haddockFlags TestFlags { @@ -960,6 +961,7 @@ convertToLegacyPerPackageConfig PackageConfig {..} = haddockCabalFilePath = mempty, haddockIndex = packageConfigHaddockIndex, haddockBaseUrl = packageConfigHaddockBaseUrl, + haddockLib = packageConfigHaddockLib, haddockArgs = mempty } @@ -1280,6 +1282,7 @@ legacyPackageConfigFieldDescrs = , "executables", "tests", "benchmarks", "all", "internal", "css" , "hyperlink-source", "quickjump", "hscolour-css" , "contents-location", "index-location", "keep-temp-files", "base-url" + , "lib" ] . commandOptionsToFields ) (haddockOptions ParseArgs) diff --git a/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs b/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs index 464f4b3744f..9a2b967067c 100644 --- a/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs +++ b/cabal-install/src/Distribution/Client/ProjectConfig/Types.hs @@ -289,6 +289,7 @@ data PackageConfig packageConfigHaddockContents :: Flag PathTemplate, --TODO: [required eventually] use this packageConfigHaddockIndex :: Flag PathTemplate, --TODO: [required eventually] use this packageConfigHaddockBaseUrl :: Flag String, --TODO: [required eventually] use this + packageConfigHaddockLib :: Flag String, --TODO: [required eventually] use this packageConfigHaddockForHackage :: Flag HaddockTarget, -- Test options packageConfigTestHumanLog :: Flag PathTemplate, diff --git a/cabal-install/src/Distribution/Client/ProjectPlanning.hs b/cabal-install/src/Distribution/Client/ProjectPlanning.hs index 20a1ab1e864..1b54ff5f908 100644 --- a/cabal-install/src/Distribution/Client/ProjectPlanning.hs +++ b/cabal-install/src/Distribution/Client/ProjectPlanning.hs @@ -1956,6 +1956,7 @@ elaborateInstallPlan verbosity platform compiler compilerprogdb pkgConfigDB elabHaddockContents = perPkgOptionMaybe pkgid packageConfigHaddockContents elabHaddockIndex = perPkgOptionMaybe pkgid packageConfigHaddockIndex elabHaddockBaseUrl = perPkgOptionMaybe pkgid packageConfigHaddockBaseUrl + elabHaddockLib = perPkgOptionMaybe pkgid packageConfigHaddockLib elabTestMachineLog = perPkgOptionMaybe pkgid packageConfigTestMachineLog elabTestHumanLog = perPkgOptionMaybe pkgid packageConfigTestHumanLog @@ -3766,6 +3767,7 @@ setupHsHaddockFlags (ElaboratedConfiguredPackage{..}) _ verbosity builddir = haddockCabalFilePath = mempty, haddockIndex = maybe mempty toFlag elabHaddockIndex, haddockBaseUrl = maybe mempty toFlag elabHaddockBaseUrl, + haddockLib = maybe mempty toFlag elabHaddockLib, haddockArgs = mempty } @@ -3920,7 +3922,8 @@ packageHashConfigInputs shared@ElaboratedSharedConfig{..} pkg = pkgHashHaddockQuickJump = elabHaddockQuickJump, pkgHashHaddockContents = elabHaddockContents, pkgHashHaddockIndex = elabHaddockIndex, - pkgHashHaddockBaseUrl = elabHaddockBaseUrl + pkgHashHaddockBaseUrl = elabHaddockBaseUrl, + pkgHashHaddockLib = elabHaddockLib } where ElaboratedConfiguredPackage{..} = normaliseConfiguredPackage shared pkg diff --git a/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs b/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs index 02b8bf774ba..bda338897e4 100644 --- a/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs +++ b/cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs @@ -294,6 +294,7 @@ data ElaboratedConfiguredPackage elabHaddockContents :: Maybe PathTemplate, elabHaddockIndex :: Maybe PathTemplate, elabHaddockBaseUrl :: Maybe String, + elabHaddockLib :: Maybe String, elabTestMachineLog :: Maybe PathTemplate, elabTestHumanLog :: Maybe PathTemplate, diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs index 1ddb9995494..3164fa5a232 100644 --- a/cabal-install/src/Distribution/Client/Setup.hs +++ b/cabal-install/src/Distribution/Client/Setup.hs @@ -1749,7 +1749,7 @@ haddockOptions showOrParseArgs , name `elem` ["hoogle", "html", "html-location" ,"executables", "tests", "benchmarks", "all", "internal", "css" ,"hyperlink-source", "quickjump", "hscolour-css" - ,"contents-location", "use-index", "for-hackage", "base-url"] + ,"contents-location", "use-index", "for-hackage", "base-url", "lib"] ] testOptions :: ShowOrParseArgs -> [OptionField TestFlags] diff --git a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs b/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs index 9d2acf3c753..46f280235a6 100644 --- a/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs +++ b/cabal-install/tests/UnitTests/Distribution/Client/ProjectConfig.hs @@ -572,6 +572,7 @@ instance Arbitrary PackageConfig where <*> arbitrary <*> arbitrary <*> arbitraryFlag arbitraryShortToken + <*> arbitraryFlag arbitraryShortToken <*> arbitrary <*> arbitrary <*> arbitrary @@ -638,6 +639,7 @@ instance Arbitrary PackageConfig where , packageConfigHaddockForHackage = x41 , packageConfigHaddockIndex = x54 , packageConfigHaddockBaseUrl = x55 + , packageConfigHaddockLib = x56 , packageConfigTestHumanLog = x44 , packageConfigTestMachineLog = x45 , packageConfigTestShowDetails = x46 @@ -697,6 +699,7 @@ instance Arbitrary PackageConfig where , packageConfigHaddockForHackage = x41' , packageConfigHaddockIndex = x54' , packageConfigHaddockBaseUrl = x55' + , packageConfigHaddockLib = x56' , packageConfigTestHumanLog = x44' , packageConfigTestMachineLog = x45' , packageConfigTestShowDetails = x46' @@ -714,7 +717,8 @@ instance Arbitrary PackageConfig where (x30', x31', x32', (x33', x33_1'), x34'), (x35', x36', x37', x38', x43', x39'), (x40', x41'), - (x44', x45', x46', x47', x48', x49', x51', x52', x54', x55'))) + (x44', x45', x46', x47', x48', x49', x51', x52', x54', x55'), + x56')) <- shrink (((preShrink_Paths x00, preShrink_Args x01, x02, x03, x04), (x05, x42, x06, x50, x07, x08, x09), @@ -728,7 +732,7 @@ instance Arbitrary PackageConfig where (x30, x31, x32, (x33, x33_1), x34), (x35, x36, fmap NonEmpty x37, x38, x43, fmap NonEmpty x39), (x40, x41), - (x44, x45, x46, x47, x48, x49, x51, x52, x54, x55))) + (x44, x45, x46, x47, x48, x49, x51, x52, x54, x55), x56)) ] where preShrink_Paths = Map.map NonEmpty From 44748dae5227e8ce5f1d3f0e79f6cf08d32f0369 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 20:38:47 +0200 Subject: [PATCH 09/19] Fix --with-haddock option It was broken in various ways :/ * The CmdHaddock (and CmdHaddockProject) have to restore the paths set with 'haddockProgramPath' (or 'haddockProjectProgramPath'); * haddock is not by default in 'ProgramDb'; We need to add it first, otherwise 'reconfigure' will not update its path. * 'setupHsHaddockFlags', need to store haddock location in 'haddockProgramPaths. This patch also adds 'haddockProjectProgramPath' and 'haddockProjectProgramArgs' to 'HaddockProjectFlags' which are passed to 'CmdHaddockProject'. --- Cabal/src/Distribution/Simple/Setup.hs | 17 +++++++++++- .../src/Distribution/Client/CmdHaddock.hs | 23 ++++++++++++++-- .../Distribution/Client/CmdHaddockProject.hs | 27 +++++++++++++++---- .../Distribution/Client/ProjectPlanning.hs | 8 ++++-- 4 files changed, 65 insertions(+), 10 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index 463d213d7c8..d5d710286dc 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -1588,6 +1588,8 @@ data HaddockProjectFlags = HaddockProjectFlags { -- options passed to @haddock@ via 'HaddockFlags' when building -- documentation + haddockProjectProgramPaths :: [(String, FilePath)], + haddockProjectProgramArgs :: [(String, [String])], -- haddockHtml is not supported -- haddockForHackage is not supported haddockProjectExecutables :: Flag Bool, @@ -1616,6 +1618,8 @@ defaultHaddockProjectFlags = HaddockProjectFlags { haddockProjectGenIndex = Flag False, haddockProjectGenContents = Flag False, haddockProjectTestSuites = Flag False, + haddockProjectProgramPaths = mempty, + haddockProjectProgramArgs = mempty, haddockProjectExecutables = Flag False, haddockProjectBenchmarks = Flag False, haddockProjectForeignLibs = Flag False, @@ -1642,8 +1646,19 @@ haddockProjectCommand = CommandUI , "COMPONENTS [FLAGS]" ] , commandDefaultFlags = defaultHaddockProjectFlags - , commandOptions = haddockProjectOptions + , commandOptions = \showOrParseArgs -> + haddockProjectOptions showOrParseArgs + ++ programDbPaths progDb ParseArgs + haddockProjectProgramPaths (\v flags -> flags { haddockProjectProgramPaths = v}) + ++ programDbOption progDb showOrParseArgs + haddockProjectProgramArgs (\v fs -> fs { haddockProjectProgramArgs = v }) + ++ programDbOptions progDb ParseArgs + haddockProjectProgramArgs (\v flags -> flags { haddockProjectProgramArgs = v}) } + where + progDb = addKnownProgram haddockProgram + $ addKnownProgram ghcProgram + $ emptyProgramDb haddockProjectOptions :: ShowOrParseArgs -> [OptionField HaddockProjectFlags] haddockProjectOptions _showOrParseArgs = diff --git a/cabal-install/src/Distribution/Client/CmdHaddock.hs b/cabal-install/src/Distribution/Client/CmdHaddock.hs index 32881099073..2a982bf4aef 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddock.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddock.hs @@ -16,6 +16,8 @@ import Distribution.Client.Compat.Prelude import Prelude () import Distribution.Client.ProjectOrchestration +import Distribution.Client.ProjectPlanning + ( ElaboratedSharedConfig(..) ) import Distribution.Client.CmdErrorMessages import Distribution.Client.TargetProblem ( TargetProblem (..), TargetProblem' ) @@ -27,6 +29,10 @@ import Distribution.Simple.Setup ( HaddockFlags(..), fromFlagOrDefault, trueArg ) import Distribution.Simple.Command ( CommandUI(..), usageAlternatives, ShowOrParseArgs, OptionField, option ) +import Distribution.Simple.Program.Builtin + ( haddockProgram ) +import Distribution.Simple.Program.Db + ( addKnownProgram, reconfigurePrograms ) import Distribution.Verbosity ( normal ) import Distribution.Simple.Utils @@ -118,8 +124,21 @@ haddockAction flags@NixStyleFlags {..} targetStrings globalFlags = do printPlan verbosity baseCtx buildCtx - buildOutcomes <- runProjectBuildPhase verbosity baseCtx buildCtx - runProjectPostBuildPhase verbosity baseCtx buildCtx buildOutcomes + progs <- reconfigurePrograms verbosity + (haddockProgramPaths haddockFlags) + (haddockProgramArgs haddockFlags) + -- we need to insert 'haddockProgram' before we reconfigure it, + -- otherwise 'set + . addKnownProgram haddockProgram + . pkgConfigCompilerProgs + . elaboratedShared + $ buildCtx + let buildCtx' = buildCtx { elaboratedShared = + (elaboratedShared buildCtx) + { pkgConfigCompilerProgs = progs } } + + buildOutcomes <- runProjectBuildPhase verbosity baseCtx buildCtx' + runProjectPostBuildPhase verbosity baseCtx buildCtx' buildOutcomes where verbosity = fromFlagOrDefault normal (configVerbosity configFlags) cliConfig = commandLineFlagsToProjectConfig globalFlags flags mempty -- ClientInstallFlags, not needed here diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 16bbc72e8a1..8eb858791c0 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -52,6 +52,10 @@ import Distribution.Simple.Haddock (createHaddockIndex) import Distribution.Simple.Utils ( die', createDirectoryIfMissingVerbose , copyDirectoryRecursive, ) +import Distribution.Simple.Program.Builtin + ( haddockProgram ) +import Distribution.Simple.Program.Db + ( addKnownProgram, reconfigurePrograms ) import Distribution.Simple.Setup ( HaddockFlags(..), defaultHaddockFlags , HaddockProjectFlags(..) @@ -74,6 +78,8 @@ haddockProjectAction flags _extraArgs globalFlags = do let haddockFlags = defaultHaddockFlags { haddockHtml = Flag True , haddockBaseUrl = Flag ".." + , haddockProgramPaths = haddockProjectProgramPaths flags + , haddockProgramArgs = haddockProjectProgramArgs flags , haddockExecutables = haddockProjectExecutables flags , haddockTestSuites = haddockProjectTestSuites flags , haddockBenchmarks = haddockProjectBenchmarks flags @@ -136,10 +142,21 @@ haddockProjectAction flags _extraArgs globalFlags = do pkgs :: [ElaboratedConfiguredPackage] pkgs = matchingPackages elaboratedPlan + + progs <- reconfigurePrograms verbosity + (haddockProjectProgramPaths flags) + (haddockProjectProgramArgs flags) + -- we need to insert 'haddockProgram' before we reconfigure it, + -- otherwise 'set + . addKnownProgram haddockProgram + . pkgConfigCompilerProgs + $ sharedConfig + let sharedConfig' = sharedConfig { pkgConfigCompilerProgs = progs } + packageNames <- fmap (nub . catMaybes) $ for pkgs $ \package -> if elabLocalToProject package then do - let distDirParams = elabDistDirParams sharedConfig package + let distDirParams = elabDistDirParams sharedConfig' package buildDir = distBuildDirectory distLayout distDirParams packageName = unPackageName (pkgName $ elabPkgSourceId package) let docDir = buildDir @@ -154,7 +171,7 @@ haddockProjectAction flags _extraArgs globalFlags = do else do let packageName = unPackageName (pkgName $ elabPkgSourceId package) packageDir = storePackageDirectory (cabalStoreDirLayout cabalLayout) - (compilerId (pkgConfigCompiler sharedConfig)) + (compilerId (pkgConfigCompiler sharedConfig')) (elabUnitId package) docDir = packageDir "share" "doc" "html" destDir = outputDir packageName @@ -176,9 +193,9 @@ haddockProjectAction flags _extraArgs globalFlags = do ] } createHaddockIndex verbosity - (pkgConfigCompilerProgs sharedConfig) - (pkgConfigCompiler sharedConfig) - (pkgConfigPlatform sharedConfig) + (pkgConfigCompilerProgs sharedConfig') + (pkgConfigCompiler sharedConfig') + (pkgConfigPlatform sharedConfig') flags' where verbosity = fromFlagOrDefault normal (haddockProjectVerbosity flags) diff --git a/cabal-install/src/Distribution/Client/ProjectPlanning.hs b/cabal-install/src/Distribution/Client/ProjectPlanning.hs index 1b54ff5f908..84905db5e15 100644 --- a/cabal-install/src/Distribution/Client/ProjectPlanning.hs +++ b/cabal-install/src/Distribution/Client/ProjectPlanning.hs @@ -3743,9 +3743,13 @@ setupHsHaddockFlags :: ElaboratedConfiguredPackage -> Verbosity -> FilePath -> Cabal.HaddockFlags -setupHsHaddockFlags (ElaboratedConfiguredPackage{..}) _ verbosity builddir = +setupHsHaddockFlags (ElaboratedConfiguredPackage{..}) (ElaboratedSharedConfig{..}) verbosity builddir = Cabal.HaddockFlags { - haddockProgramPaths = mempty, --unused, set at configure time + haddockProgramPaths = + case lookupProgram haddockProgram pkgConfigCompilerProgs of + Nothing -> mempty + Just prg -> [( programName haddockProgram + , locationPath (programLocation prg) )], haddockProgramArgs = mempty, --unused, set at configure time haddockHoogle = toFlag elabHaddockHoogle, haddockHtml = toFlag elabHaddockHtml, From 095244c2d8e8ba19344afc16f7a188f1ab7fb2e6 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 24 May 2022 22:57:03 +0200 Subject: [PATCH 10/19] Added support for hoogle for the haddock-project command --- Cabal/src/Distribution/Simple/Setup.hs | 7 +++++++ cabal-install/src/Distribution/Client/CmdHaddockProject.hs | 1 + 2 files changed, 8 insertions(+) diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index d5d710286dc..072979739a1 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -1590,6 +1590,7 @@ data HaddockProjectFlags = HaddockProjectFlags { haddockProjectProgramPaths :: [(String, FilePath)], haddockProjectProgramArgs :: [(String, [String])], + haddockProjectHoogle :: Flag Bool, -- haddockHtml is not supported -- haddockForHackage is not supported haddockProjectExecutables :: Flag Bool, @@ -1620,6 +1621,7 @@ defaultHaddockProjectFlags = HaddockProjectFlags { haddockProjectTestSuites = Flag False, haddockProjectProgramPaths = mempty, haddockProjectProgramArgs = mempty, + haddockProjectHoogle = Flag False, haddockProjectExecutables = Flag False, haddockProjectBenchmarks = Flag False, haddockProjectForeignLibs = Flag False, @@ -1682,6 +1684,11 @@ haddockProjectOptions _showOrParseArgs = haddockProjectGenContents (\v flags -> flags { haddockProjectGenContents = v}) trueArg + ,option "" ["hoogle"] + "Generate a hoogle database" + haddockProjectHoogle (\v flags -> flags { haddockProjectHoogle = v }) + trueArg + ,option "" ["executables"] "Run haddock for Executables targets" haddockProjectExecutables (\v flags -> flags { haddockProjectExecutables = v }) diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 8eb858791c0..761f29f1146 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -80,6 +80,7 @@ haddockProjectAction flags _extraArgs globalFlags = do , haddockBaseUrl = Flag ".." , haddockProgramPaths = haddockProjectProgramPaths flags , haddockProgramArgs = haddockProjectProgramArgs flags + , haddockHoogle = haddockProjectHoogle flags , haddockExecutables = haddockProjectExecutables flags , haddockTestSuites = haddockProjectTestSuites flags , haddockBenchmarks = haddockProjectBenchmarks flags From 3e6e6510a088dc229344723de8c67a0a49066013 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Wed, 25 May 2022 08:42:41 +0200 Subject: [PATCH 11/19] Added support to visible / hidden modules for the haddock-project command Haddock-2.26.1 allows to configure whether modules from a given interface file should be visible on the generated content page. We make visible only modules which come from local packages. --- Cabal/src/Distribution/Simple/Haddock.hs | 42 ++++++++++++------- Cabal/src/Distribution/Simple/Setup.hs | 18 +++++--- .../Distribution/Client/CmdHaddockProject.hs | 15 ++++--- .../src/Distribution/Client/Haddock.hs | 2 +- 4 files changed, 52 insertions(+), 25 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index 4d7dab68846..5bcd37335dc 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -22,7 +22,8 @@ module Distribution.Simple.Haddock ( haddock, createHaddockIndex, hscolour, - haddockPackagePaths + haddockPackagePaths, + Visibility(..) ) where import Prelude () @@ -116,7 +117,7 @@ data HaddockArgs = HaddockArgs { argVerbose :: Any, argOutput :: Flag [Output], -- ^ HTML or Hoogle doc or both? Required. - argInterfaces :: [(FilePath, Maybe String, Maybe String)], + argInterfaces :: [(FilePath, Maybe String, Maybe String, Visibility)], -- ^ [(Interface file, URL to the HTML docs and hyperlinked-source for links)]. argOutputDir :: Directory, -- ^ Where to generate the documentation. @@ -772,17 +773,27 @@ renderPureArgs version comp platform args = concat where renderInterfaces = map renderInterface - renderInterface :: (FilePath, Maybe FilePath, Maybe FilePath) -> String - renderInterface (i, html, hypsrc) = "--read-interface=" ++ - (intercalate "," $ concat [ [ x | Just x <- [html] ] - , [ x | Just _ <- [html] - -- only render hypsrc path if html path - -- is given and hyperlinked-source is - -- enabled - , Just x <- [hypsrc] - , isVersion 2 17 - , fromFlagOrDefault False . argLinkedSource $ args - ] + renderInterface :: (FilePath, Maybe FilePath, Maybe FilePath, Visibility) -> String + renderInterface (i, html, hypsrc, visibility) = "--read-interface=" ++ + (intercalate "," $ concat [ [ fromMaybe "" html ] + , -- only render hypsrc path if html path + -- is given and hyperlinked-source is + -- enabled + [ case (html, hypsrc) of + (Nothing, _) -> "" + (_, Nothing) -> "" + (_, Just x) | isVersion 2 17 + , fromFlagOrDefault False . argLinkedSource $ args + -> x + | otherwise + -> "" + ] + , if haddockSupportsVisibility + then [ case visibility of + Visible -> "visible" + Hidden -> "hidden" + ] + else [] , [ i ] ]) @@ -791,6 +802,7 @@ renderPureArgs version comp platform args = concat verbosityFlag | isVersion 2 5 = "--verbosity=1" | otherwise = "--verbose" + haddockSupportsVisibility = version >= mkVersion [2,26,1] --------------------------------------------------------------------------------- @@ -806,6 +818,7 @@ haddockPackagePaths :: [InstalledPackageInfo] , Maybe FilePath -- url to hyperlinked -- source + , Visibility )] , Maybe String -- warning about -- missing documentation @@ -830,7 +843,7 @@ haddockPackagePaths ipkgs mkHtmlPath = do exists <- doesFileExist interface if exists - then return (Right (interface, html', hypsrc')) + then return (Right (interface, html', hypsrc', Visible)) else return (Left pkgid) | ipkg <- ipkgs, let pkgid = packageId ipkg , pkgName pkgid `notElem` noHaddockWhitelist @@ -882,6 +895,7 @@ haddockPackageFlags :: Verbosity , Maybe FilePath -- url to hyperlinked -- source + , Visibility )] , Maybe String -- warning about -- missing documentation diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index 072979739a1..8e454a74ec3 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -43,8 +43,8 @@ module Distribution.Simple.Setup ( InstallFlags(..), emptyInstallFlags, defaultInstallFlags, installCommand, HaddockTarget(..), HaddockFlags(..), emptyHaddockFlags, defaultHaddockFlags, haddockCommand, - HaddockProjectFlags(..), emptyHaddockProjectFlags, - defaultHaddockProjectFlags, haddockProjectCommand, + Visibility(..), + HaddockProjectFlags(..), emptyHaddockProjectFlags, defaultHaddockProjectFlags, haddockProjectCommand, HscolourFlags(..), emptyHscolourFlags, defaultHscolourFlags, hscolourCommand, BuildFlags(..), emptyBuildFlags, defaultBuildFlags, buildCommand, DumpBuildInfo(..), @@ -1574,15 +1574,23 @@ instance Semigroup HaddockFlags where -- * HaddocksFlags flags -- ------------------------------------------------------------ +-- | Governs whether modules from a given interface should be visible or +-- hidden in the Haddock generated content page. We don't expose this +-- functionality to the user, but simply use 'Visible' for only local packages. +-- Visibility of modules is available since @haddock-2.26.1@. +-- +data Visibility = Visible | Hidden + deriving (Eq, Show) + data HaddockProjectFlags = HaddockProjectFlags { -- options passed to @haddock@ via 'createHaddockIndex' haddockProjectDir :: Flag String, - -- ^ output directory of combined haddockProject, the default is './haddocks' + -- ^ output directory of combined haddocks, the default is './haddocks' haddockProjectPrologue :: Flag String, haddockProjectGenIndex :: Flag Bool, haddockProjectGenContents :: Flag Bool, - haddockProjectInterfaces :: Flag [(FilePath, Maybe FilePath, Maybe FilePath)], - -- ^ 'haddockProjectInterfaces' is inferred by the 'haddocksAction'; currently not + haddockProjectInterfaces :: Flag [(FilePath, Maybe FilePath, Maybe FilePath, Visibility)], + -- ^ 'haddocksInterfaces' is inferred by the 'haddocksAction'; currently not -- exposed to the user. -- options passed to @haddock@ via 'HaddockFlags' when building diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 761f29f1146..007a0966a4c 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -59,7 +59,9 @@ import Distribution.Simple.Program.Db import Distribution.Simple.Setup ( HaddockFlags(..), defaultHaddockFlags , HaddockProjectFlags(..) - , Flag(..), fromFlag, fromFlagOrDefault + , Flag(..) + , Visibility(..) + , fromFlag, fromFlagOrDefault , haddockProjectCommand ) import Distribution.Verbosity as Verbosity @@ -154,7 +156,7 @@ haddockProjectAction flags _extraArgs globalFlags = do $ sharedConfig let sharedConfig' = sharedConfig { pkgConfigCompilerProgs = progs } - packageNames <- fmap (nub . catMaybes) $ for pkgs $ \package -> + packageInfos <- fmap (nub . catMaybes) $ for pkgs $ \package -> if elabLocalToProject package then do let distDirParams = elabDistDirParams sharedConfig' package @@ -167,7 +169,7 @@ haddockProjectAction flags _extraArgs globalFlags = do a <- doesDirectoryExist docDir case a of True -> copyDirectoryRecursive verbosity docDir destDir - >> return (Just (packageName, destDir)) + >> return (Just (packageName, destDir, Visible)) False -> return Nothing else do let packageName = unPackageName (pkgName $ elabPkgSourceId package) @@ -179,7 +181,9 @@ haddockProjectAction flags _extraArgs globalFlags = do a <- doesDirectoryExist docDir case a of True -> copyDirectoryRecursive verbosity docDir destDir - >> return (Just (packageName, destDir)) + -- non local packages will be hidden in haddock's generated + -- contents page + >> return (Just (packageName, destDir, Hidden)) False -> return Nothing -- run haddock to generate index, content, etc. @@ -189,8 +193,9 @@ haddockProjectAction flags _extraArgs globalFlags = do [ ( destDir packageName <.> "haddock" , Just packageName , Just packageName + , visibility ) - | (packageName, destDir) <- packageNames + | (packageName, destDir, visibility) <- packageInfos ] } createHaddockIndex verbosity diff --git a/cabal-install/src/Distribution/Client/Haddock.hs b/cabal-install/src/Distribution/Client/Haddock.hs index 49f8869a404..862a1e6f85a 100644 --- a/cabal-install/src/Distribution/Client/Haddock.hs +++ b/cabal-install/src/Distribution/Client/Haddock.hs @@ -41,7 +41,7 @@ regenerateHaddockIndex :: Verbosity -> IO () regenerateHaddockIndex verbosity pkgs progdb index = do (paths, warns) <- haddockPackagePaths pkgs' Nothing - let paths' = [ (interface, html) | (interface, Just html, _) <- paths] + let paths' = [ (interface, html) | (interface, Just html, _, _) <- paths] for_ warns (debug verbosity) (confHaddock, _, _) <- From 6269f747d68575cd528f6854cf1391a025e64bec Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Wed, 25 May 2022 08:49:20 +0200 Subject: [PATCH 12/19] Added support for installed packages for the haddock-project command Generated haddocks will have valid links to packages distributed with GHC, e.g. `base`, `bytestring`, `array`, etc. --- .../Distribution/Client/CmdHaddockProject.hs | 100 +++++++++++------- 1 file changed, 63 insertions(+), 37 deletions(-) diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 007a0966a4c..cab0e9bf7a9 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -42,6 +42,7 @@ import Distribution.Client.TargetProblem (TargetProblem(..)) import Distribution.Types.PackageId (pkgName) import Distribution.Types.PackageName (unPackageName) +import Distribution.Types.InstalledPackageInfo (InstalledPackageInfo (..)) import Distribution.Simple.Command ( CommandUI(..) ) import Distribution.Simple.Compiler @@ -67,8 +68,8 @@ import Distribution.Simple.Setup import Distribution.Verbosity as Verbosity ( normal ) -import System.FilePath ( normalise, (), (<.>) ) -import System.Directory ( doesDirectoryExist ) +import System.FilePath ( takeDirectory, normalise, (), (<.>) ) +import System.Directory ( doesDirectoryExist, doesFileExist ) haddockProjectAction :: HaddockProjectFlags -> [String] -> GlobalFlags -> IO () haddockProjectAction flags _extraArgs globalFlags = do @@ -143,7 +144,7 @@ haddockProjectAction flags _extraArgs globalFlags = do sharedConfig :: ElaboratedSharedConfig sharedConfig = elaboratedShared buildCtx - pkgs :: [ElaboratedConfiguredPackage] + pkgs :: [Either InstalledPackageInfo ElaboratedConfiguredPackage ] pkgs = matchingPackages elaboratedPlan progs <- reconfigurePrograms verbosity @@ -156,46 +157,72 @@ haddockProjectAction flags _extraArgs globalFlags = do $ sharedConfig let sharedConfig' = sharedConfig { pkgConfigCompilerProgs = progs } - packageInfos <- fmap (nub . catMaybes) $ for pkgs $ \package -> - if elabLocalToProject package - then do - let distDirParams = elabDistDirParams sharedConfig' package - buildDir = distBuildDirectory distLayout distDirParams - packageName = unPackageName (pkgName $ elabPkgSourceId package) - let docDir = buildDir - "doc" "html" - packageName - destDir = outputDir packageName - a <- doesDirectoryExist docDir - case a of - True -> copyDirectoryRecursive verbosity docDir destDir - >> return (Just (packageName, destDir, Visible)) - False -> return Nothing - else do - let packageName = unPackageName (pkgName $ elabPkgSourceId package) - packageDir = storePackageDirectory (cabalStoreDirLayout cabalLayout) - (compilerId (pkgConfigCompiler sharedConfig')) - (elabUnitId package) - docDir = packageDir "share" "doc" "html" - destDir = outputDir packageName - a <- doesDirectoryExist docDir - case a of - True -> copyDirectoryRecursive verbosity docDir destDir - -- non local packages will be hidden in haddock's generated - -- contents page - >> return (Just (packageName, destDir, Hidden)) - False -> return Nothing + packageInfos <- fmap (nub . concat) $ for pkgs $ \pkg -> + case pkg of + Left package -> do + let packageName = unPackageName (pkgName $ sourcePackageId package) + destDir = outputDir packageName + fmap catMaybes $ for (haddockInterfaces package) $ \interfacePath -> do + let docDir = takeDirectory interfacePath + a <- doesFileExist interfacePath + case a of + True -> copyDirectoryRecursive verbosity docDir destDir + >> return (Just ( packageName + , interfacePath + , Hidden + )) + False -> return Nothing + + Right package -> + if elabLocalToProject package + then do + let distDirParams = elabDistDirParams sharedConfig' package + buildDir = distBuildDirectory distLayout distDirParams + packageName = unPackageName (pkgName $ elabPkgSourceId package) + let docDir = buildDir + "doc" "html" + packageName + destDir = outputDir packageName + interfacePath = destDir + packageName <.> "haddock" + a <- doesDirectoryExist docDir + case a of + True -> copyDirectoryRecursive verbosity docDir destDir + >> return [( packageName + , interfacePath + , Visible + )] + False -> return [] + else do + let packageName = unPackageName (pkgName $ elabPkgSourceId package) + packageDir = storePackageDirectory (cabalStoreDirLayout cabalLayout) + (compilerId (pkgConfigCompiler sharedConfig')) + (elabUnitId package) + docDir = packageDir "share" "doc" "html" + destDir = outputDir packageName + interfacePath = destDir + packageName <.> "haddock" + a <- doesDirectoryExist docDir + case a of + True -> copyDirectoryRecursive verbosity docDir destDir + -- non local packages will be hidden in haddock's + -- generated contents page + >> return [( packageName + , interfacePath + , Hidden + )] + False -> return [] -- run haddock to generate index, content, etc. let flags' = flags { haddockProjectDir = Flag outputDir , haddockProjectInterfaces = Flag - [ ( destDir packageName <.> "haddock" + [ ( interfacePath , Just packageName , Just packageName , visibility ) - | (packageName, destDir, visibility) <- packageInfos + | (packageName, interfacePath, visibility) <- packageInfos ] } createHaddockIndex verbosity @@ -223,8 +250,7 @@ haddockProjectAction flags _extraArgs globalFlags = do ts matchingPackages :: ElaboratedInstallPlan - -> [ElaboratedConfiguredPackage] + -> [Either InstalledPackageInfo ElaboratedConfiguredPackage] matchingPackages = - catMaybes - . fmap (foldPlanPackage (const Nothing) Just) + fmap (foldPlanPackage Left Right) . InstallPlan.toList From c0e6d01359bad0d7555a409a4668d1978bd16d43 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sat, 28 May 2022 07:51:47 +0200 Subject: [PATCH 13/19] Pass --package-name & --package-version to haddock It is supported at least from `haddock-2.16`. --- Cabal/src/Distribution/Simple/Haddock.hs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Cabal/src/Distribution/Simple/Haddock.hs b/Cabal/src/Distribution/Simple/Haddock.hs index 5bcd37335dc..32f34b0859d 100644 --- a/Cabal/src/Distribution/Simple/Haddock.hs +++ b/Cabal/src/Distribution/Simple/Haddock.hs @@ -699,7 +699,7 @@ renderPureArgs version comp platform args = concat [ map (\f -> "--dump-interface="++ unDir (argOutputDir args) f) . flagToList . argInterfaceFile $ args - , if isVersion 2 16 + , if haddockSupportsPackageName then maybe [] (\pkg -> [ "--package-name=" ++ prettyShow (pkgName pkg) , "--package-version=" ++ prettyShow (pkgVersion pkg) ]) @@ -803,6 +803,7 @@ renderPureArgs version comp platform args = concat | isVersion 2 5 = "--verbosity=1" | otherwise = "--verbose" haddockSupportsVisibility = version >= mkVersion [2,26,1] + haddockSupportsPackageName = version > mkVersion [2,16] --------------------------------------------------------------------------------- From f035633fbd427977a68c3145d2ed7547ba2cbe43 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sun, 29 May 2022 06:19:05 +0200 Subject: [PATCH 14/19] Support --haddock-html-location By passing `--haddock-html-location` one can link to haddocks to documentation published on hackage. However one can use it or `--base-url`. The latter will build self contained directory of haddock documentation. --- Cabal/src/Distribution/Simple/Setup.hs | 7 ++ .../Distribution/Client/CmdHaddockProject.hs | 98 +++++++++++-------- 2 files changed, 64 insertions(+), 41 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index 8e454a74ec3..b9586775717 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -1600,6 +1600,7 @@ data HaddockProjectFlags = HaddockProjectFlags { haddockProjectProgramArgs :: [(String, [String])], haddockProjectHoogle :: Flag Bool, -- haddockHtml is not supported + haddockProjectHtmlLocation :: Flag String, -- haddockForHackage is not supported haddockProjectExecutables :: Flag Bool, haddockProjectTestSuites :: Flag Bool, @@ -1630,6 +1631,7 @@ defaultHaddockProjectFlags = HaddockProjectFlags { haddockProjectProgramPaths = mempty, haddockProjectProgramArgs = mempty, haddockProjectHoogle = Flag False, + haddockProjectHtmlLocation = NoFlag, haddockProjectExecutables = Flag False, haddockProjectBenchmarks = Flag False, haddockProjectForeignLibs = Flag False, @@ -1697,6 +1699,11 @@ haddockProjectOptions _showOrParseArgs = haddockProjectHoogle (\v flags -> flags { haddockProjectHoogle = v }) trueArg + ,option "" ["html-location"] + "Location of HTML documentation for pre-requisite packages" + haddockProjectHtmlLocation (\v flags -> flags { haddockProjectHtmlLocation = v }) + (reqArgFlag "URL") + ,option "" ["executables"] "Run haddock for Executables targets" haddockProjectExecutables (\v flags -> flags { haddockProjectExecutables = v }) diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index cab0e9bf7a9..469c71ac07b 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -80,9 +80,12 @@ haddockProjectAction flags _extraArgs globalFlags = do -- build all packages with appropriate haddock flags let haddockFlags = defaultHaddockFlags { haddockHtml = Flag True - , haddockBaseUrl = Flag ".." + -- one can either use `--haddock-base-url` or + -- `--haddock-html-location`. + , haddockBaseUrl = if localStyle then Flag ".." else NoFlag , haddockProgramPaths = haddockProjectProgramPaths flags , haddockProgramArgs = haddockProjectProgramArgs flags + , haddockHtmlLocation = haddockProjectHtmlLocation flags , haddockHoogle = haddockProjectHoogle flags , haddockExecutables = haddockProjectExecutables flags , haddockTestSuites = haddockProjectTestSuites flags @@ -93,8 +96,10 @@ haddockProjectAction flags _extraArgs globalFlags = do , haddockLinkedSource = haddockProjectLinkedSource flags , haddockQuickJump = haddockProjectQuickJump flags , haddockHscolourCss = haddockProjectHscolourCss flags - , haddockContents = Flag (toPathTemplate "../index.html") - , haddockIndex = Flag (toPathTemplate "../doc-index.html") + , haddockContents = if localStyle then Flag (toPathTemplate "../index.html") + else NoFlag + , haddockIndex = if localStyle then Flag (toPathTemplate "../doc-index.html") + else NoFlag , haddockKeepTempFiles= haddockProjectKeepTempFiles flags , haddockVerbosity = haddockProjectVerbosity flags , haddockLib = haddockProjectLib flags @@ -159,6 +164,8 @@ haddockProjectAction flags _extraArgs globalFlags = do packageInfos <- fmap (nub . concat) $ for pkgs $ \pkg -> case pkg of + Left _ | not localStyle -> + return [] Left package -> do let packageName = unPackageName (pkgName $ sourcePackageId package) destDir = outputDir packageName @@ -174,44 +181,46 @@ haddockProjectAction flags _extraArgs globalFlags = do False -> return Nothing Right package -> - if elabLocalToProject package - then do - let distDirParams = elabDistDirParams sharedConfig' package - buildDir = distBuildDirectory distLayout distDirParams - packageName = unPackageName (pkgName $ elabPkgSourceId package) - let docDir = buildDir - "doc" "html" - packageName - destDir = outputDir packageName - interfacePath = destDir - packageName <.> "haddock" - a <- doesDirectoryExist docDir - case a of - True -> copyDirectoryRecursive verbosity docDir destDir - >> return [( packageName - , interfacePath - , Visible - )] - False -> return [] - else do - let packageName = unPackageName (pkgName $ elabPkgSourceId package) - packageDir = storePackageDirectory (cabalStoreDirLayout cabalLayout) - (compilerId (pkgConfigCompiler sharedConfig')) - (elabUnitId package) - docDir = packageDir "share" "doc" "html" - destDir = outputDir packageName - interfacePath = destDir - packageName <.> "haddock" - a <- doesDirectoryExist docDir - case a of - True -> copyDirectoryRecursive verbosity docDir destDir - -- non local packages will be hidden in haddock's - -- generated contents page - >> return [( packageName - , interfacePath - , Hidden - )] - False -> return [] + case elabLocalToProject package of + True -> do + let distDirParams = elabDistDirParams sharedConfig' package + buildDir = distBuildDirectory distLayout distDirParams + packageName = unPackageName (pkgName $ elabPkgSourceId package) + let docDir = buildDir + "doc" "html" + packageName + destDir = outputDir packageName + interfacePath = destDir + packageName <.> "haddock" + a <- doesDirectoryExist docDir + case a of + True -> copyDirectoryRecursive verbosity docDir destDir + >> return [( packageName + , interfacePath + , Visible + )] + False -> return [] + False | not localStyle -> + return [] + False -> do + let packageName = unPackageName (pkgName $ elabPkgSourceId package) + packageDir = storePackageDirectory (cabalStoreDirLayout cabalLayout) + (compilerId (pkgConfigCompiler sharedConfig')) + (elabUnitId package) + docDir = packageDir "share" "doc" "html" + destDir = outputDir packageName + interfacePath = destDir + packageName <.> "haddock" + a <- doesDirectoryExist docDir + case a of + True -> copyDirectoryRecursive verbosity docDir destDir + -- non local packages will be hidden in haddock's + -- generated contents page + >> return [( packageName + , interfacePath + , Hidden + )] + False -> return [] -- run haddock to generate index, content, etc. let flags' = flags @@ -233,6 +242,13 @@ haddockProjectAction flags _extraArgs globalFlags = do where verbosity = fromFlagOrDefault normal (haddockProjectVerbosity flags) + -- Build a self contained directory which contains haddocks of all + -- transitive dependencies; or depend on `--haddocks-html-location` to + -- provide location of the documentation of dependencies. + localStyle = case haddockProjectHtmlLocation flags of + NoFlag -> True + Flag _ -> False + reportTargetProblems :: Show x => [x] -> IO a reportTargetProblems = die' verbosity . unlines . map show From 6e40a8b946455a8d4178e9430b5333beab3679fa Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sun, 29 May 2022 08:11:10 +0200 Subject: [PATCH 15/19] Added --local and --hackage options for haddocks command --- Cabal/src/Distribution/Simple/Setup.hs | 37 ++++++++++- .../Distribution/Client/CmdHaddockProject.hs | 64 +++++++++++++++---- 2 files changed, 88 insertions(+), 13 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Setup.hs b/Cabal/src/Distribution/Simple/Setup.hs index b9586775717..5791e2fbf8f 100644 --- a/Cabal/src/Distribution/Simple/Setup.hs +++ b/Cabal/src/Distribution/Simple/Setup.hs @@ -1583,6 +1583,23 @@ data Visibility = Visible | Hidden deriving (Eq, Show) data HaddockProjectFlags = HaddockProjectFlags { + haddockProjectHackage :: Flag Bool, + -- ^ a shortcut option which builds documentation linked to hackage. It implies: + -- * `--html-location='https://hackage.haskell.org/package/$prg-$version/docs' + -- * `--quickjump` + -- * `--gen-index` + -- * `--gen-contents` + -- * `--hyperlinked-source` + haddockProjectLocal :: Flag Bool, + -- ^ a shortcut option which builds self contained directory which contains + -- all the documentation, it implies: + -- * `--quickjump` + -- * `--gen-index` + -- * `--gen-contents` + -- * `--hyperlinked-source` + -- + -- And it will also pass `--base-url` option to `haddock`. + -- options passed to @haddock@ via 'createHaddockIndex' haddockProjectDir :: Flag String, -- ^ output directory of combined haddocks, the default is './haddocks' @@ -1623,6 +1640,8 @@ data HaddockProjectFlags = HaddockProjectFlags { defaultHaddockProjectFlags :: HaddockProjectFlags defaultHaddockProjectFlags = HaddockProjectFlags { + haddockProjectHackage = Flag False, + haddockProjectLocal = Flag False, haddockProjectDir = Flag "./haddocks", haddockProjectPrologue = NoFlag, haddockProjectGenIndex = Flag False, @@ -1674,7 +1693,23 @@ haddockProjectCommand = CommandUI haddockProjectOptions :: ShowOrParseArgs -> [OptionField HaddockProjectFlags] haddockProjectOptions _showOrParseArgs = - [option "" ["output"] + [option "" ["hackage"] + (concat ["A short-cut option to build documentation linked to hackage; " + ,"it implies --quickjump, --gen-index, --gen-contents, " + ,"--hyperlinked-source and --html-location" + ]) + haddockProjectHackage (\v flags -> flags { haddockProjectHackage = v }) + trueArg + + ,option "" ["local"] + (concat ["A short-cut option to build self contained documentation; " + ,"it implies --quickjump, --gen-index, --gen-contents " + ,"and --hyperlinked-source." + ]) + haddockProjectLocal (\v flags -> flags { haddockProjectLocal = v }) + trueArg + + ,option "" ["output"] "Output directory" haddockProjectDir (\v flags -> flags { haddockProjectDir = v }) (optArg' "DIRECTORY" maybeToFlag (fmap Just . flagToList)) diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 469c71ac07b..4933adac111 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -4,6 +4,7 @@ module Distribution.Client.CmdHaddockProject ) where import Prelude () +import Data.Bool (bool) import Distribution.Client.Compat.Prelude hiding (get) import qualified Distribution.Client.CmdBuild as CmdBuild @@ -47,6 +48,13 @@ import Distribution.Simple.Command ( CommandUI(..) ) import Distribution.Simple.Compiler ( Compiler (..) ) +import Distribution.Simple.Flag + ( Flag(..) + , flagElim + , flagToList + , fromFlag + , fromFlagOrDefault + ) import Distribution.Simple.InstallDirs ( toPathTemplate ) import Distribution.Simple.Haddock (createHaddockIndex) @@ -60,9 +68,7 @@ import Distribution.Simple.Program.Db import Distribution.Simple.Setup ( HaddockFlags(..), defaultHaddockFlags , HaddockProjectFlags(..) - , Flag(..) , Visibility(..) - , fromFlag, fromFlagOrDefault , haddockProjectCommand ) import Distribution.Verbosity as Verbosity @@ -77,15 +83,26 @@ haddockProjectAction flags _extraArgs globalFlags = do let outputDir = normalise $ fromFlag (haddockProjectDir flags) createDirectoryIfMissingVerbose verbosity True outputDir + when ((2::Int) <= + ( flagElim 0 (bool 0 1) (haddockProjectHackage flags) + + flagElim 0 (bool 0 1) (haddockProjectLocal flags) + + flagElim 0 (const 1) (haddockProjectHtmlLocation flags) + )) $ + die' verbosity "Options `--local`, `--hackage` and `--html-location` are mutually exclusive`" + -- build all packages with appropriate haddock flags let haddockFlags = defaultHaddockFlags { haddockHtml = Flag True -- one can either use `--haddock-base-url` or -- `--haddock-html-location`. - , haddockBaseUrl = if localStyle then Flag ".." else NoFlag + , haddockBaseUrl = if localStyle + then Flag ".." + else NoFlag , haddockProgramPaths = haddockProjectProgramPaths flags , haddockProgramArgs = haddockProjectProgramArgs flags - , haddockHtmlLocation = haddockProjectHtmlLocation flags + , haddockHtmlLocation = if fromFlagOrDefault False (haddockProjectHackage flags) + then Flag "https://hackage.haskell.org/package/$pkg-$version/docs" + else haddockProjectHtmlLocation flags , haddockHoogle = haddockProjectHoogle flags , haddockExecutables = haddockProjectExecutables flags , haddockTestSuites = haddockProjectTestSuites flags @@ -93,9 +110,13 @@ haddockProjectAction flags _extraArgs globalFlags = do , haddockForeignLibs = haddockProjectForeignLibs flags , haddockInternal = haddockProjectInternal flags , haddockCss = haddockProjectCss flags - , haddockLinkedSource = haddockProjectLinkedSource flags - , haddockQuickJump = haddockProjectQuickJump flags - , haddockHscolourCss = haddockProjectHscolourCss flags + , haddockLinkedSource = if localOrHackage + then Flag True + else haddockProjectLinkedSource flags + , haddockQuickJump = if localOrHackage + then Flag True + else haddockProjectQuickJump flags + , haddockHscolourCss = haddockProjectHscolourCss flags , haddockContents = if localStyle then Flag (toPathTemplate "../index.html") else NoFlag , haddockIndex = if localStyle then Flag (toPathTemplate "../doc-index.html") @@ -224,8 +245,18 @@ haddockProjectAction flags _extraArgs globalFlags = do -- run haddock to generate index, content, etc. let flags' = flags - { haddockProjectDir = Flag outputDir - , haddockProjectInterfaces = Flag + { haddockProjectDir = Flag outputDir + , haddockProjectGenIndex = if localOrHackage + then Flag True + else haddockProjectGenIndex flags + , haddockProjectGenContents = if localOrHackage + then Flag True + else haddockProjectGenContents flags + , haddockProjectQuickJump = if localOrHackage + then Flag True + else haddockProjectQuickJump flags + , haddockProjectLinkedSource = haddockLinkedSource haddockFlags + , haddockProjectInterfaces = Flag [ ( interfacePath , Just packageName , Just packageName @@ -245,9 +276,18 @@ haddockProjectAction flags _extraArgs globalFlags = do -- Build a self contained directory which contains haddocks of all -- transitive dependencies; or depend on `--haddocks-html-location` to -- provide location of the documentation of dependencies. - localStyle = case haddockProjectHtmlLocation flags of - NoFlag -> True - Flag _ -> False + localStyle = + let local = fromFlagOrDefault False (haddockProjectLocal flags) + hackage = fromFlagOrDefault False (haddockProjectHackage flags) + location = fromFlagOrDefault False (const True <$> haddockProjectHtmlLocation flags) + in local && not hackage && not location + -- or if none of the flags is given set `localStyle` to `True` + || not local && not hackage && not location + + + localOrHackage = + any id $ flagToList (haddockProjectLocal flags) + ++ flagToList (haddockProjectHackage flags) reportTargetProblems :: Show x => [x] -> IO a reportTargetProblems = From a5e9c12c5e4277482eba434d1eafea02f6c05533 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sun, 29 May 2022 08:25:18 +0200 Subject: [PATCH 16/19] Added experimental warning to the haddocks command. --- cabal-install/src/Distribution/Client/CmdHaddockProject.hs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 4933adac111..3b0c39e3e7b 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -60,7 +60,7 @@ import Distribution.Simple.InstallDirs import Distribution.Simple.Haddock (createHaddockIndex) import Distribution.Simple.Utils ( die', createDirectoryIfMissingVerbose - , copyDirectoryRecursive, ) + , copyDirectoryRecursive, warn ) import Distribution.Simple.Program.Builtin ( haddockProgram ) import Distribution.Simple.Program.Db @@ -90,6 +90,8 @@ haddockProjectAction flags _extraArgs globalFlags = do )) $ die' verbosity "Options `--local`, `--hackage` and `--html-location` are mutually exclusive`" + warn verbosity "haddock-project command is experimental, it might break in the future" + -- build all packages with appropriate haddock flags let haddockFlags = defaultHaddockFlags { haddockHtml = Flag True From b8fb12a5df2e1453422f97fb93808fdbcfb88554 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sun, 29 May 2022 08:54:26 +0200 Subject: [PATCH 17/19] Haddocks command requires haddock-2.26.1 --- .../Distribution/Client/CmdHaddockProject.hs | 36 +++++++++++++++---- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs index 3b0c39e3e7b..65af69233c9 100644 --- a/cabal-install/src/Distribution/Client/CmdHaddockProject.hs +++ b/cabal-install/src/Distribution/Client/CmdHaddockProject.hs @@ -43,6 +43,8 @@ import Distribution.Client.TargetProblem (TargetProblem(..)) import Distribution.Types.PackageId (pkgName) import Distribution.Types.PackageName (unPackageName) +import Distribution.Types.Version (mkVersion) +import Distribution.Types.VersionRange (orLaterVersion) import Distribution.Types.InstalledPackageInfo (InstalledPackageInfo (..)) import Distribution.Simple.Command ( CommandUI(..) ) @@ -64,7 +66,7 @@ import Distribution.Simple.Utils import Distribution.Simple.Program.Builtin ( haddockProgram ) import Distribution.Simple.Program.Db - ( addKnownProgram, reconfigurePrograms ) + ( addKnownProgram, reconfigurePrograms, requireProgramVersion ) import Distribution.Simple.Setup ( HaddockFlags(..), defaultHaddockFlags , HaddockProjectFlags(..) @@ -133,12 +135,12 @@ haddockProjectAction flags _extraArgs globalFlags = do (NixStyleOptions.configFlags (commandDefaultFlags CmdBuild.buildCommand)) { configVerbosity = haddockProjectVerbosity flags } } - CmdHaddock.haddockAction - nixFlags - ["all"] - globalFlags - -- copy local packages to the destination directory + -- + -- Construct the build plan and infer the list of packages which haddocks + -- we need. + -- + withContextAndSelectors RejectNoTargets Nothing nixFlags ["all"] globalFlags $ \targetCtx ctx targetSelectors -> do baseCtx <- case targetCtx of ProjectContext -> return ctx @@ -185,6 +187,23 @@ haddockProjectAction flags _extraArgs globalFlags = do $ sharedConfig let sharedConfig' = sharedConfig { pkgConfigCompilerProgs = progs } + _ <- requireProgramVersion + verbosity haddockProgram + (orLaterVersion (mkVersion [2,26,1])) progs + + -- + -- Build haddocks of each components + -- + + CmdHaddock.haddockAction + nixFlags + ["all"] + globalFlags + + -- + -- Copy haddocks to the destination folder + -- + packageInfos <- fmap (nub . concat) $ for pkgs $ \pkg -> case pkg of Left _ | not localStyle -> @@ -245,7 +264,10 @@ haddockProjectAction flags _extraArgs globalFlags = do )] False -> return [] - -- run haddock to generate index, content, etc. + -- + -- generate index, content, etc. + -- + let flags' = flags { haddockProjectDir = Flag outputDir , haddockProjectGenIndex = if localOrHackage From 88078b434572e9bcb1e7e556cc5f4e5e544c9fd7 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sun, 29 May 2022 09:13:29 +0200 Subject: [PATCH 18/19] Added changelog entry for this PR --- changelog.d/pr-8162 | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 changelog.d/pr-8162 diff --git a/changelog.d/pr-8162 b/changelog.d/pr-8162 new file mode 100644 index 00000000000..ab1ae51bb8e --- /dev/null +++ b/changelog.d/pr-8162 @@ -0,0 +1,17 @@ +synopsis: Added haddocks command +packages: cabal-install +prs: #8162 +issues: #7669 +description: { + +The `haddock-package` command can be used to build documentation of multiple +packages. By passing `--local` option the directory will be self contained, +by passing `--hackage` links to dependencies will link to `hackage`. Both +`--local` and `--hackage` options imply `--quickfix`, `--gen-index`, +`--gen-contents`, and `--hyperlinked-source`. + +Building self contained directory is the default, unless `--hackage` or +`--html-location`. + +The PR #8162 also fixes the `--with-haddock` option. +} From eee9bacbc53fd1286e9fab58ace26f187e7f528c Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sun, 29 May 2022 09:37:15 +0200 Subject: [PATCH 19/19] Added documentation of haddocks command. --- doc/cabal-commands.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst index ddc5abdcdd3..f48a70f0285 100644 --- a/doc/cabal-commands.rst +++ b/doc/cabal-commands.rst @@ -33,6 +33,7 @@ legacy sections. We talk in detail about some global and package commands. freeze Freeze dependencies. haddock Build Haddock documentation. + haddock-project Build Haddock documentation of local packages. exec Give a command access to the store. list-bin List path to a single executable. @@ -581,6 +582,31 @@ If a target is not a library :cfg-field:`haddock-benchmarks`, :cfg-field:`haddock-executables`, :cfg-field:`haddock-internal`, :cfg-field:`haddock-tests` will be implied as necessary. +cabal haddock-project +--------------------- + +``cabal haddock-project [FLAGS]`` builds Haddock documentation for all local +packages specified in the project. + +By default the documentation will be put in ``./haddocks`` folder, this can be +modified with the ``--output`` flag. + +This command supports two primary modes: building a self contained directory +(by specifying ``--local`` flag) or documentation that links to hackage (with +``--hackage`` flag). Both options imply: ``--quickjump``, ``--gen-index``, +``--gen-contents`` and ``--hyperlinked-source``. + +If neither ``--local`` nor ``--hackage`` option is specified a self contained +directory will only be build if ``--html-location`` is not specified. + +In both cases the html index as well as quickjump index will include all terms +and types defined in any of the local packages, but not ones that are included +in any of the dependencies. But note that if you navigate to a dependency, +you will have access to its quickjump index. + +The generated landing page will contain one tree of all modules per local +package. + cabal exec ----------