Merge pull request #397 from Profpatsch/document-readHaskellHaddock

Action/Generate: Add the PR documentation to `readHaskellHaddock`

src/Action/Generate.hs

@@ -177,6 +177,27 @@ readHaskellGhcpkg timing settings = do
                     in Map.map (\p -> p{packageTags = ts ++ packageTags p}) cbl
     pure (cbl, Map.keysSet cbl, source)
 
+-- | @hoogle generate --haddock=path/to/doc@ works similarly to @hoogle generate --local@,
+-- getting package info from a local ghc-pkg database, but uses @path/to/doc@
+-- as the canonical source of Haddock documentation.
+-- @path/to/doc@ should be a path to the directory that contains the root @index.html@
+-- generated by cabal haddock or stack haddock.
+-- Paths stored in the database are relative to this root.
+--
+-- @hoogle server --haddock=path/to/doc@ is intended to be used with a database
+-- containing relative paths. In contrast to @hoogle server --local@,
+-- paths relative to the filesystem root are not allowed;
+-- only files from @path/to/doc@ are served.
+--
+-- These features are intended to be used together, when you want to
+-- create a Hoogle index for your project in one place, then serve it somewhere else.
+-- This enables a workflow such as the following:
+--
+-- 1. Run cabal haddock or stack haddock on your build server
+-- 2. Run hoogle generate --haddock=path/to/doc on your build server (this assumes you know where the docs were written)
+-- 3. Deploy the Hoogle database and Haddock files to your documentation server & run hoogle server --haddock=new/path/to/doc
+--
+-- from https://github.com/ndmitchell/hoogle/pull/202
 readHaskellHaddock :: Timing -> Settings -> FilePath -> IO (Map.Map PkgName Package, Set.Set PkgName, ConduitT () (PkgName, URL, LBStr) IO ())
 readHaskellHaddock timing settings docBaseDir = do
     cbl <- timed timing "Reading ghc-pkg" $ readGhcPkg settings