Commit 693e5863 authored by Jan Rasmus Tikovsky 's avatar Jan Rasmus Tikovsky
Browse files

Added option to CurryDoc to generate index file categorizing all libraries of a Curry System

parent 0337e952
......@@ -76,26 +76,30 @@ bootstrapForm rootdir styles title lefttopmenu righttopmenu
--- @param header - the main header (rendered with hero-unit style)
--- @param contents - the main contents of the document
--- @param footer - the footer of the document
--- @param isIndex - flag to generate index page with header
--- (using whole page width)
bootstrapPage :: String -> [String] -> String -> [[HtmlExp]]
-> [[HtmlExp]] -> Int -> [HtmlExp] -> [HtmlExp]
-> [HtmlExp] -> [HtmlExp] -> HtmlPage
-> [HtmlExp] -> [HtmlExp] -> Bool -> HtmlPage
bootstrapPage rootdir styles title lefttopmenu righttopmenu
leftcols sidemenu header contents footer =
leftcols sidemenu header contents footer isIndex =
HtmlPage title
([pageEnc "utf-8",responsiveView,icon] ++
map (\n -> pageCSS (rootdir++"/css/"++n++".css")) styles)
(topNavigationBar lefttopmenu righttopmenu ++
[blockstyle "container-fluid"
[blockstyle "row-fluid"
(if leftcols==0
then [headerRow, blockstyle "row-fluid" contents]
else [blockstyle ("span"++show leftcols)
[blockstyle "well sidebar-nav" sidemenu],
blockstyle ("span"++show (12-leftcols))
[headerRow,
blockstyle "row-fluid" contents]]),
hrule,
HtmlStruct "footer" [] footer]])
then fluidBlock $ [headerRow, blockstyle "row-fluid" contents]
++ footline
else (if isIndex
then [blockstyle "container-fluid" [headerRow]]
++ (fluidBlock $ sidemenuBlock
++ [blockstyle ("span" ++ show (12-leftcols))
contentBlock]
++ footline)
else fluidBlock $ sidemenuBlock
++ [blockstyle ("span" ++ show (12-leftcols))
(headerRow : contentBlock)]
++ footline)))
where
-- for a better view on handheld devices:
responsiveView =
......@@ -109,6 +113,18 @@ bootstrapPage rootdir styles title lefttopmenu righttopmenu
headerRow = blockstyle "row-fluid"
[HtmlStruct "header" [("class","hero-unit")] header]
-- content block
contentBlock = [blockstyle "row-fluid" contents]
-- sidemenu block
sidemenuBlock = [ blockstyle ("span"++show leftcols)
[blockstyle "well sidebar-nav" sidemenu] ]
-- footline
footline = [hrule, HtmlStruct "footer" [] footer]
fluidBlock b = [blockstyle "container-fluid" [blockstyle "row-fluid" b]]
-- Navigation bar at the top:
topNavigationBar :: [[HtmlExp]] -> [[HtmlExp]] -> [HtmlExp]
topNavigationBar leftmenu rightmenu =
......
......@@ -2,8 +2,8 @@
--- Implementation of CurryDoc, a utility for the automatic
--- generation of HTML documentation from Curry programs.
---
--- @author Michael Hanus
--- @version January 2015
--- @author Michael Hanus, Jan Tikovsky
--- @version June 2015
----------------------------------------------------------------------
-- * All comments to be put into the HTML documentation must be
......@@ -34,6 +34,7 @@ import FileGoodies
import FilePath ((</>), (<.>), dropFileName, takeFileName)
import FlatCurry
import FlatCurryRead(readFlatCurryWithImports)
import Function
import List
import Maybe(fromJust)
import System
......@@ -85,6 +86,8 @@ processArgs params args = case args of
-- HTML index only
("--onlyindexhtml":docdir:modnames) ->
makeIndexPages docdir (map stripCurrySuffix modnames)
("--libsindexhtml":docdir:modnames) ->
makeSystemLibsIndex docdir modnames
(('-':_):_) -> putStrLn usageMessage
-- module
[modname] ->
......@@ -103,6 +106,7 @@ usageMessage = unlines
, "Usage: currydoc [--nomarkdown] [--html|--tex|--cdoc] [<doc directory>] <module_name>"
, " currydoc [--nomarkdown] --noindexhtml <doc directory> <module_name>"
, " currydoc --onlyindexhtml <doc directory> <module_names>"
, " currydoc --libsindexhtml <doc directory> <module_names>"
]
......@@ -177,6 +181,37 @@ makeIndexPages docdir modnames = do
(Prog _ _ types funs _) <- readFlatCurryFile fcyfile
return (types,funs)
--- Generate a system library index page categorizing the given
--- (already compiled!) modules
makeSystemLibsIndex :: String -> [String] -> IO ()
makeSystemLibsIndex docdir modnames = do
-- generate index pages (main index, function index, constructor index)
makeIndexPages docdir modnames
putStrLn ("Categorizing modules ...")
modInfos <- mapIO getModInfo modnames
putStrLn ("Grouping modules by categories ...")
let grpMods = map sortByName $ groupByCategory $ sortByCategory modInfos
cats = sortBy (<=) $ nub $ map fst3 modInfos
genSystemLibsPage docdir cats grpMods
where
fst3 (x,_,_) = x
snd3 (_,y,_) = y
trd3 (_,_,z) = z
sortByCategory = sortBy ((<=) `on` fst3)
groupByCategory = groupBy ((==) `on` fst3)
sortByName = sortBy ((<=) `on` snd3)
getModInfo :: String -> IO (Category,String, String)
getModInfo modname = do
mmodsrc <- lookupModuleSourceInLoadPath modname
case mmodsrc of
Nothing -> error $ "Source code of module '"++modname++"' not found!"
Just (_,progname) -> do
(modcmts,_) <- readComments progname
let (modcmt,catcmts) = splitComment modcmts
category = readCategory $ getCommentType "category" catcmts
return (category,modname,firstPassage modcmt)
-- create documentation directory (if necessary) with gifs and stylesheets:
prepareDocDir :: DocType -> String -> IO ()
prepareDocDir HtmlDoc docdir = do
......
......@@ -2,8 +2,8 @@
--- This module contains some configuration parameters for
--- the CurryDoc tool.
---
--- @author Michael Hanus
--- @version January 2015
--- @author Michael Hanus, Jan Tikovsky
--- @version June 2015
----------------------------------------------------------------------
module CurryDocConfig where
......@@ -12,7 +12,7 @@ import Distribution(curryCompiler)
--- Version of currydoc
currydocVersion :: String
currydocVersion = "Version 0.7.3 of January 27, 2015"
currydocVersion = "Version 0.8.0 of June 4, 2015"
--- The URL of the base directory containing the styles, images, etc.
baseURL :: String
......@@ -23,3 +23,11 @@ baseURL = if curryCompiler=="pakcs"
--- The name of this Curry system.
currySystem :: String
currySystem = if curryCompiler=="pakcs" then "PAKCS" else "KiCS2"
--- The URL of the API search
currygleURL :: String
currygleURL = "https://www-ps.informatik.uni-kiel.de/kics2/currygle/"
--- The URL of the Curry homepage
curryHomeURL :: String
curryHomeURL = "http://www.curry-language.org"
----------------------------------------------------------------------
--- Operations to generate documentation in HTML format.
---
--- @author Michael Hanus
--- @version January 2015
--- @author Michael Hanus, Jan Tikovsky
--- @version June 2015
----------------------------------------------------------------------
module CurryDocHtml where
......@@ -59,6 +59,7 @@ generateHtmlDocs docparams anainfo modname modcmts progcmts = do
[anchoredSection "exported_operations"
[h2 [htxt "Exported operations:"]]] ++
(map (genHtmlFunc docparams modname progcmts anainfo ops) expfuns)))
False
where
title = "Module "++modname
......@@ -589,6 +590,78 @@ genConsIndexPage docdir types = do
htmlConsIndex :: [QName] -> [HtmlExp]
htmlConsIndex qnames = categorizeByItemKey (map showModNameRef qnames)
--------------------------------------------------------------------------
-- generate the index page categorizing all system libraries of PAKCS/KICS2
genSystemLibsPage :: String -> [Category] -> [[ModInfo]] -> IO ()
genSystemLibsPage docdir cats modInfos = do
putStrLn $ "Writing main index page for " ++ currySystem ++
" to \"" ++ fname ++ "\"..."
mainPage (currySystem ++ " Libraries")
[h1 [htxt $ currySystem ++ ": System Libraries"]]
syslibsLeftTopMenu
syslibsRightTopMenu
3
(syslibsSideMenu cats)
([infoTxt, hrule] ++ genHtmlLibCats modInfos)
True
>>= writeFile fname
where
fname = docdir ++ "/" ++ currySystem ++ "_libs.html"
syslibsLeftTopMenu :: [[HtmlExp]]
syslibsLeftTopMenu =
[ [href baseURL [htxt currySystem]]
, [href (baseURL ++ "/Manual.pdf") [htxt "Manual (PDF)"]]
, [href (baseURL ++ "/lib/") [htxt "Libraries"]]
, [ehref currygleURL [extLinkIcon, htxt " API Search"]]
, [href (baseURL ++ "/download.html") [htxt "Download"]]
]
syslibsRightTopMenu :: [[HtmlExp]]
syslibsRightTopMenu =
[ curryHomeItem
, [ehref (curryHomeURL ++ "/documentation/report")
[extLinkIcon, htxt " Curry Report"]]
]
syslibsSideMenu :: [Category] -> [HtmlExp]
syslibsSideMenu cats = map par $
[[ehref currygleURL [extLinkIcon, htxt " Search with Curr(y)gle"]]]
++ [[href ("#" ++ genCatLink c) [ htxt (showCategory c)]] | c <- cats]
++ [ [href "findex.html" [htxt "Index to all library functions"]]
, [href "cindex.html" [htxt "Index to all library constructors"]]
]
infoTxt :: HtmlExp
infoTxt = par
[ htxt "Here is the collection of libraries contained in the distribution of "
, href baseURL [htxt currySystem]
, htxt $ ". Most of these libraries have been implemented during the "
++ "development of larger Curry applications. If you have suggestions "
++ "for changes/improvements or if you want to contribute your own "
++ "library, please contact "
, href "http://www.informatik.uni-kiel.de/~mh/" [htxt "Michael Hanus"]
, htxt "."
]
-- Generate links for a category (system libraries page)
genCatLink :: Category -> String
genCatLink cat = getCategoryID cat
genHtmlLibCats :: [[ModInfo]] -> [HtmlExp]
genHtmlLibCats [] = []
genHtmlLibCats (cat:cats) = case cat of
[] -> []
((c,_,_):_) ->
[anchoredSection (getCategoryID c) [h2 [htxt (showCategory c ++ ":")]]]
++ genHtmlLibCat cat
++ genHtmlLibCats cats
genHtmlLibCat :: [ModInfo] -> [HtmlExp]
genHtmlLibCat category =
[dlist [(genHtmlName modname,[htxt modcmt]) | (_,modname,modcmt) <- category ]]
where
genHtmlName modname = [code [href (modname ++ ".html") [htxt modname]]]
--------------------------------------------------------------------------
-- Auxiliary operation for general page style.
......@@ -600,15 +673,16 @@ htmlConsIndex qnames = categorizeByItemKey (map showModNameRef qnames)
--- @param righttopmenu - the menu shown at right of the top
--- @param columns - number of columns for the left-side menu
--- @param sidemenu - the menu shown at the left-hand side
--- @param doc - the main contents of the page
--- @param maindoc - the main contents of the page
--- @param isIndex - flag to generate libs index page
mainPage :: String -> [HtmlExp] -> [[HtmlExp]] -> [[HtmlExp]] -> Int
-> [HtmlExp] -> [HtmlExp] -> IO String
mainPage title htmltitle lefttopmenu righttopmenu columns sidemenu maindoc = do
-> [HtmlExp] -> [HtmlExp] -> Bool -> IO String
mainPage title htmltitle lefttopmenu righttopmenu columns sidemenu maindoc isIndex = do
time <- getLocalTime
return $ showHtmlPage $
bootstrapPage baseURL cssIncludes
title lefttopmenu righttopmenu columns sidemenu htmltitle maindoc
(curryDocFooter time)
(curryDocFooter time) isIndex
cssIncludes :: [String]
cssIncludes = ["bootstrap","bootstrap-responsive","font-awesome.min","currydoc"]
......@@ -626,15 +700,15 @@ showPageWithDocStyle title body =
--- The standard right top menu.
rightTopMenu :: [[HtmlExp]]
rightTopMenu =
[[ehref "http://www.curry-language.org/"
[extLinkIcon, htxt " Curry Homepage"]],
[ehref (baseURL++"/lib/")
[extLinkIcon, htxt $ " "++currySystem++" Libraries"]],
[ehref "http://www.curry-language.org/tools/currydoc"
[extLinkIcon, htxt " About CurryDoc"]]]
where
extLinkIcon = italic [] `addClass` "fa fa-external-link"
[ curryHomeItem
, [ehref (baseURL++"/lib/")
[extLinkIcon, htxt $ " "++currySystem++" Libraries"]]
, [ehref (curryHomeURL ++ "/tools/currydoc")
[extLinkIcon, htxt " About CurryDoc"]]
]
extLinkIcon :: HtmlExp
extLinkIcon = italic [] `addClass` "fa fa-external-link"
-- Standard footer information for generated web pages:
curryDocFooter :: CalendarTime -> [HtmlExp]
......@@ -644,6 +718,9 @@ curryDocFooter time =
htxt (" ("++currydocVersion++") at "),
htxt (calendarTimeToString time)]]
curryHomeItem :: [HtmlExp]
curryHomeItem = [ehref curryHomeURL [extLinkIcon, htxt " Curry Homepage"]]
--- Generate a simple page with the default documentation style.
--- @param title - the title of the page
--- @param htmltitle - maybe a specific title for h1 header
......@@ -658,6 +735,7 @@ simplePage title htmltitle lefttopmenu maindoc = do
[h1 (maybe [htxt title] id htmltitle)]
maindoc
(curryDocFooter time)
False
--- An anchored section in the document:
anchoredSection :: String -> [HtmlExp] -> HtmlExp
......@@ -693,10 +771,14 @@ sortStrings strings = mergeSort leqStringIgnoreCase strings
-- Returns the first sentence in a string:
firstSentence :: String -> String
firstSentence s = let (fs,ls) = break (=='.') s in
if ls==""
if null ls
then fs
else if tail ls /= "" && isWhiteSpace (head (tail ls))
then fs ++ "."
else fs ++ "." ++ firstSentence (tail ls)
firstPassage :: String -> String
firstPassage = unlines . takeWhile (\s -> s /= "" && not (all isWhiteSpace s))
. lines
--------------------------------------------------------------------------
----------------------------------------------------------------------
--- Some auxiliary operations of CurryDoc to read programs.
---
--- @author Michael Hanus
--- @version January 2015
--- @author Michael Hanus, Jan Tikovsky
--- @version June 2015
----------------------------------------------------------------------
module CurryDocRead where
......@@ -31,12 +31,50 @@ data SourceLine = Comment String -- a comment for CurryDoc
| ModDef -- a line containing a module definition
| OtherLine -- a line not relevant for CurryDoc
--- This datatype is used to categorize Curry libraries
--- @cons General - a general library
--- @cons Algorithm - a library which provides data structures and algorithms
--- @cons Web - a library for web applications
--- @cons Meta - a library for meta-programming
data Category = General
| Algorithm
| Web
| Meta
type ModInfo = (Category, String, String)
--- Determine the category for a module
readCategory :: [String] -> Category
readCategory [] = General
readCategory (catcmt:_) = case cat of
"general" -> General
"algorithm" -> Algorithm
"web" -> Web
"meta" -> Meta
_ -> General
where
(cat,_) = span isIdChar catcmt
--- Show a category
showCategory :: Category -> String
showCategory General = "General libraries"
showCategory Algorithm = "Data structures and algorithms"
showCategory Web = "Libraries for web applications"
showCategory Meta = "Libraries for meta-programming"
--- ID for a category
getCategoryID :: Category -> String
getCategoryID General = "general"
getCategoryID Algorithm = "algorithm"
getCategoryID Web = "web"
getCategoryID Meta = "meta"
-- classify a line of the source program:
-- here we replace blank line comments by a "breakline" tag
classifyLine :: String -> SourceLine
classifyLine line
| take 3 line == "---" && all isSpace (drop 3 line) = Comment "" --"<br/>"
| take 4 line == "--- " = Comment (drop 4 line)
| take 4 line == "--- " && head (drop 4 line) /= '-' = Comment (drop 4 line)
| take 7 line == "module " = ModDef
| take 7 line == "import " = ModDef
| otherwise = let id1 = getFirstId line
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment