Allow Idris to install IdrisDoc into a central location.

+ Default location is `<getDataDir>/docs`.
+ Flag `--info` has been updated to show doc location.
+ New flag `--installdoc <ipkg>` provided to install documentation
+ New flag `--docdir` provided to show documentation installation location.
+ New environment variable `IDRIS_DOC_PATH` to allow alternate means of customisation.
+ Installation for Idris' std libraries has been augmented to install library documentation as well.

Author: Jan de Muijnck-Hughes

Setup.hs

@@ -268,7 +268,6 @@ idrisInstall verbosity copy pkg local = unless (execOnly (configFlags local)) $
          notice verbosity $ unwords ["Copying man page to", mandest]
          installOrdinaryFiles verbosity mandest [("man", "idris.1")]
 
-
       makeInstall src target =
          make verbosity [ "-C", src, "install" , "TARGET=" ++ target, "IDRIS=" ++ idrisCmd local]
 

libs/Makefile

@@ -34,5 +34,4 @@ doc_clean:
 	$(MAKE)	-C effects doc_clean
 	$(MAKE)	-C pruviloj doc_clean
 
-
 .PHONY: build install clean doc doc_clean

libs/base/Makefile

@@ -4,8 +4,9 @@ PKG := base
 build:
 	$(IDRIS) --build ${PKG}.ipkg
 
-install: 
+install:
 	$(IDRIS) --install ${PKG}.ipkg
+	${IDRIS} --installdoc ${PKG}.ipkg
 
 clean:
 	$(IDRIS) --clean ${PKG}.ipkg
@@ -21,4 +22,4 @@ doc_clean:
 linecount:
 	find . -name '*.idr' | xargs wc -l
 
-.PHONY: build install clean rebuild linecount
+.PHONY: build install clean rebuild linecount doc doc_clean

libs/contrib/Makefile

@@ -4,8 +4,9 @@ PKG := contrib
 build:
 	$(IDRIS) --build ${PKG}.ipkg
 
-install: 
+install:
 	$(IDRIS) --install ${PKG}.ipkg
+	${IDRIS} --installdoc ${PKG}.ipkg
 
 clean:
 	$(IDRIS) --clean ${PKG}.ipkg
@@ -21,4 +22,4 @@ doc_clean:
 linecount:
 	find . -name '*.idr' | xargs wc -l
 
-.PHONY: build install clean rebuild linecount
+.PHONY: build install clean rebuild linecount doc doc_clean

libs/effects/Makefile

@@ -9,6 +9,7 @@ clean:
 
 install:
 	$(IDRIS) --install ${PKG}.ipkg
+	${IDRIS} --installdoc ${PKG}.ipkg
 
 rebuild: clean build
 

libs/prelude/Makefile

@@ -4,8 +4,9 @@ PKG   := prelude
 build:
 	$(IDRIS) --build ${PKG}.ipkg
 
-install: 
+install:
 	$(IDRIS) --install ${PKG}.ipkg
+	${IDRIS} --installdoc ${PKG}.ipkg
 
 clean:
 	$(IDRIS) --clean ${PKG}.ipkg

libs/pruviloj/Makefile

@@ -9,6 +9,7 @@ clean:
 
 install:
 	$(IDRIS) --install ${PKG}.ipkg
+	${IDRIS} --installdoc ${PKG}.ipkg
 
 rebuild: clean build
 

main/Main.hs

@@ -18,7 +18,8 @@ processShowOptions opts = runIO $ do
   when (ShowLoggingCats `elem` opts)  $ showExitIdrisLoggingCategories
   when (ShowIncs `elem` opts)         $ showExitIdrisFlagsInc
   when (ShowLibs `elem` opts)         $ showExitIdrisFlagsLibs
-  when (ShowLibdir `elem` opts)       $ showExitIdrisLibDir
+  when (ShowLibDir `elem` opts)       $ showExitIdrisLibDir
+  when (ShowDocDir `elem` opts)       $ showExitIdrisDocDir
   when (ShowPkgs `elem` opts)         $ showExitIdrisInstalledPackages
 
 check :: [Opt] -> (Opt -> Maybe a) -> ([a] -> Idris ()) -> Idris ()

src/IRTS/System.hs

@@ -12,6 +12,7 @@ module IRTS.System( getDataFileName
                   , getCC
                   , getLibFlags
                   , getIdrisLibDir
+                  , getIdrisDocDir
                   , getIncFlags
                   , getEnvFlags
                   , version
@@ -31,23 +32,31 @@ import Paths_idris (version)
 import Paths_idris
 #endif
 
-overrideDataDirWith :: String -> IO FilePath
-overrideDataDirWith envVar = do
+overrideIdrisDirWith :: String  -- ^ Sub directory in `getDataDir` location.
+                     -> String  -- ^ Environment variable to get new location from.
+                     -> IO FilePath
+overrideIdrisDirWith fp envVar = do
   envValue <- lookupEnv envVar
   case envValue of
     Nothing -> do
       ddir <- getDataDir
-      return (ddir </> "libs")
+      return (ddir </> fp)
     Just ddir -> return ddir
 
+overrideIdrisLibDirWith :: String -> IO FilePath
+overrideIdrisLibDirWith = overrideIdrisDirWith "libs"
+
+overrideIdrisDocDirWith :: String -> IO FilePath
+overrideIdrisDocDirWith = overrideIdrisDirWith "docs"
+
 getCC :: IO String
 getCC = fromMaybe "gcc" <$> lookupEnv "IDRIS_CC"
 
 getEnvFlags :: IO [String]
 getEnvFlags = maybe [] (splitOn " ") <$> lookupEnv "IDRIS_CFLAGS"
 
 getTargetDir :: IO String
-getTargetDir = overrideDataDirWith "TARGET"
+getTargetDir = overrideIdrisLibDirWith "TARGET"
 
 #if defined(freebsd_HOST_OS) || defined(dragonfly_HOST_OS)\
     || defined(openbsd_HOST_OS) || defined(netbsd_HOST_OS)
@@ -68,7 +77,10 @@ getLibFlags = do dir <- getDataDir
                  return $ ["-L" ++ (dir </> "rts"),
                            "-lidris_rts"] ++ extraLib ++ gmpLib ++ ["-lpthread"]
 
-getIdrisLibDir = addTrailingPathSeparator <$> overrideDataDirWith "IDRIS_LIBRARY_PATH"
+getIdrisLibDir = addTrailingPathSeparator <$> overrideIdrisLibDirWith "IDRIS_LIBRARY_PATH"
+
+getIdrisDocDir = addTrailingPathSeparator <$> overrideIdrisDocDirWith "IDRIS_DOC_PATH"
+
 
 getIncFlags = do dir <- getDataDir
                  return $ ("-I" ++ dir </> "rts") : extraInclude

src/Idris/AbsSyntax.hs

@@ -2545,7 +2545,7 @@ getPkgDir (Pkg str) = Just str
 getPkgDir _ = Nothing
 
 getPkg :: Opt -> Maybe (Bool, String)
-getPkg (PkgBuild str) = Just (False, str)
+getPkg (PkgBuild   str) = Just (False, str)
 getPkg (PkgInstall str) = Just (True, str)
 getPkg _ = Nothing
 
@@ -2563,9 +2563,10 @@ getPkgCheck _              = Nothing
 
 -- | Returns None if given an Opt which is not PkgMkDoc
 --   Otherwise returns Just x, where x is the contents of PkgMkDoc
-getPkgMkDoc :: Opt          -- ^ Opt to extract
-            -> Maybe String -- ^ Result
-getPkgMkDoc (PkgMkDoc str) = Just str
+getPkgMkDoc :: Opt                  -- ^ Opt to extract
+            -> Maybe (Bool, String) -- ^ Result
+getPkgMkDoc (PkgDocBuild  str)  = Just (False,str)
+getPkgMkDoc (PkgDocInstall str) = Just (True,str)
 getPkgMkDoc _              = Nothing
 
 getPkgTest :: Opt          -- ^ the option to extract

src/Idris/AbsSyntaxTree.hs

@@ -492,7 +492,8 @@ data Opt = Filename String
          | IdemodeSocket
          | ShowAll
          | ShowLibs
-         | ShowLibdir
+         | ShowLibDir
+         | ShowDocDir
          | ShowIncs
          | ShowPkgs
          | ShowLoggingCats
@@ -524,7 +525,8 @@ data Opt = Filename String
          | PkgClean String
          | PkgCheck String
          | PkgREPL String
-         | PkgMkDoc String -- IdrisDoc
+         | PkgDocBuild String -- IdrisDoc
+         | PkgDocInstall String
          | PkgTest String
          | PkgIndex FilePath
          | WarnOnly

src/Idris/CmdOptions.hs

@@ -129,7 +129,8 @@ parseFlags = many $
   <|> flag' ShowLoggingCats (long "listlogcats" <> help "Display logging categories")
   <|> flag' ShowLibs        (long "link"        <> help "Display link flags")
   <|> flag' ShowPkgs        (long "listlibs"    <> help "Display installed libraries")
-  <|> flag' ShowLibdir      (long "libdir"      <> help "Display library directory")
+  <|> flag' ShowLibDir      (long "libdir"      <> help "Display library directory")
+  <|> flag' ShowDocDir      (long "docdir"      <> help "Display idrisdoc install directory")
   <|> flag' ShowIncs        (long "include"     <> help "Display the includes flags")
 
   <|> flag' Verbose (short 'V' <> long "verbose" <> help "Loud verbosity")
@@ -144,13 +145,14 @@ parseFlags = many $
   <|> (Port <$> option portReader (long "port" <> metavar "PORT" <> help "REPL TCP port - pass \"none\" to not bind any port"))
 
   -- Package commands
-  <|> (PkgBuild   <$> strOption (long "build"    <> metavar "IPKG" <> help "Build package"))
-  <|> (PkgInstall <$> strOption (long "install"  <> metavar "IPKG" <> help "Install package"))
-  <|> (PkgREPL    <$> strOption (long "repl"     <> metavar "IPKG" <> help "Launch REPL, only for executables"))
-  <|> (PkgClean   <$> strOption (long "clean"    <> metavar "IPKG" <> help "Clean package"))
-  <|> (PkgMkDoc   <$> strOption (long "mkdoc"    <> metavar "IPKG" <> help "Generate IdrisDoc for package"))
-  <|> (PkgCheck   <$> strOption (long "checkpkg" <> metavar "IPKG" <> help "Check package only"))
-  <|> (PkgTest    <$> strOption (long "testpkg"  <> metavar "IPKG" <> help "Run tests for package"))
+  <|> (PkgBuild      <$> strOption (long "build"      <> metavar "IPKG" <> help "Build package"))
+  <|> (PkgInstall    <$> strOption (long "install"    <> metavar "IPKG" <> help "Install package"))
+  <|> (PkgREPL       <$> strOption (long "repl"       <> metavar "IPKG" <> help "Launch REPL, only for executables"))
+  <|> (PkgClean      <$> strOption (long "clean"      <> metavar "IPKG" <> help "Clean package"))
+  <|> (PkgDocBuild   <$> strOption (long "mkdoc"      <> metavar "IPKG" <> help "Generate IdrisDoc for package"))
+  <|> (PkgDocInstall <$> strOption (long "installdoc" <> metavar "IPKG" <> help "Install IdrisDoc for package"))
+  <|> (PkgCheck      <$> strOption (long "checkpkg"   <> metavar "IPKG" <> help "Check package only"))
+  <|> (PkgTest       <$> strOption (long "testpkg"    <> metavar "IPKG" <> help "Run tests for package"))
 
   -- Misc options
   <|> (BCAsm <$> strOption (long "bytecode"))

src/Idris/Info.hs

@@ -7,6 +7,7 @@ Maintainer  : The Idris Community.
 -}
 module Idris.Info
   ( getIdrisLibDir
+  , getIdrisDocDir
   , getIdrisFlagsLib
   , getIdrisFlagsInc
   , getIdrisFlagsEnv
@@ -33,6 +34,9 @@ import Version_idris (gitHash)
 
 import Paths_idris
 
+getIdrisDocDir :: IO String
+getIdrisDocDir = S.getIdrisDocDir
+
 getIdrisLibDir :: IO String
 getIdrisLibDir = S.getIdrisLibDir
 

src/Idris/Info/Show.hs

@@ -24,6 +24,16 @@ showExitIdrisLibDir = do
   showIdrisLibDir
   exitSuccess
 
+showIdrisDocDir :: IO ()
+showIdrisDocDir = do
+  ldir <- getIdrisDocDir
+  putStrLn ldir
+
+showExitIdrisDocDir :: IO ()
+showExitIdrisDocDir = do
+  showIdrisDocDir
+  exitSuccess
+
 showIdrisFlagsInc :: IO ()
 showIdrisFlagsInc = do
   incFlags <- getIdrisFlagsInc
@@ -68,8 +78,10 @@ showIdrisInfo = do
   putStrLn "Paths:"
   ldir <- getIdrisLibDir
   udir <- getIdrisUserDataDir
+  ddir <- getIdrisDocDir
   putStrLn $ unwords ["-", "Library Dir:", ldir]
   putStrLn $ unwords ["-", "User Dir:",    udir]
+  putStrLn $ unwords ["-", "Documentation Dir:", ddir]
 
   putStrLn "Flags:"
   lflag <- getIdrisFlagsLib

src/Idris/Package.hs

@@ -190,10 +190,10 @@ cleanPkg copts fp = do
 --
 -- Issue number #1572 on the issue tracker
 --       https://github.com/idris-lang/Idris-dev/issues/1572
-documentPkg :: [Opt]    -- ^ Command line options.
-            -> FilePath -- ^ Path to ipkg file.
+documentPkg :: [Opt]           -- ^ Command line options.
+            -> (Bool,FilePath) -- ^ (Should we install?, Path to ipkg file).
             -> IO ()
-documentPkg copts fp = do
+documentPkg copts (install,fp) = do
   pkgdesc        <- parseDesc fp
   cd             <- getCurrentDirectory
   let pkgDir      = cd </> takeDirectory fp
@@ -223,7 +223,13 @@ documentPkg copts fp = do
           putStrLn $ pshow idrisInit err
           exitWith (ExitFailure 1)
         Right ist -> do
-          docRes <- generateDocs ist mods outputDir
+          iDocDir   <- getIdrisDocDir
+          pkgDocDir <- makeAbsolute (iDocDir </> pkgname pkgdesc)
+          let out_dir = if install then pkgDocDir else outputDir
+          when install $ do
+              putStrLn $ unwords ["Attempting to install IdrisDocs for", pkgname pkgdesc, "in:", out_dir]
+
+          docRes <- generateDocs ist mods out_dir
           case docRes of
             Right _  -> return ()
             Left msg -> do
@@ -416,14 +422,15 @@ mergeOptions copts popts =
     normaliseOpts = filter filtOpt
 
     filtOpt :: Opt -> Bool
-    filtOpt (PkgBuild   _) = False
-    filtOpt (PkgInstall _) = False
-    filtOpt (PkgClean   _) = False
-    filtOpt (PkgCheck   _) = False
-    filtOpt (PkgREPL    _) = False
-    filtOpt (PkgMkDoc   _) = False
-    filtOpt (PkgTest    _) = False
-    filtOpt _              = True
+    filtOpt (PkgBuild        _) = False
+    filtOpt (PkgInstall      _) = False
+    filtOpt (PkgClean        _) = False
+    filtOpt (PkgCheck        _) = False
+    filtOpt (PkgREPL         _) = False
+    filtOpt (PkgDocBuild     _) = False
+    filtOpt (PkgDocInstall   _) = False
+    filtOpt (PkgTest         _) = False
+    filtOpt _                   = True
 
     chkOpt :: Opt -> Either String Opt
     chkOpt o@(OLogging _)     = Right o