shake: cleanups, document

[ci skip]
This commit is contained in:
Simon Michael 2019-01-19 14:49:20 -08:00
parent 1077ccf70c
commit b7e64440b2

226
Shake.hs
View File

@ -30,6 +30,9 @@ Usage: see below. Also:
$ find hledger-lib hledger | entr ./Shake website # rebuild web files on changes in these dirs
Shake rule dependency graph:
file:///Users/simon/src/PLAINTEXTACCOUNTING/hledger/report.html?mode=rule-graph&query=!name(/(doc%7Cimages%7Cjs%7Ccss%7Cfonts%7Ctime%7Capi%7Cui%7Ccsv)/)
Shake wishes:
just one shake import
wildcards in phony rules
@ -47,22 +50,20 @@ import "safe" Safe
import "shake" Development.Shake
import "shake" Development.Shake.FilePath
import "time" Data.Time
-- import "hledger-lib" Hledger.Utils.Debug
usage = unlines
["Usage:"
,"./Shake.hs # compile this script"
,"./Shake [help] # show commands"
,"./Shake manuals # generate the txt/man/info manuals"
,"./Shake website # generate the website and web manuals"
,"./Shake all # generate everything"
,"./Shake manuals # generate the plaintext/man/info manuals"
,"./Shake website # generate the html manuals and website"
-- ,"./Shake manpages # generate nroff files for man"
-- ,"./Shake txtmanpages # generate text man pages for embedding"
-- ,"./Shake infomanpages # generate info files for info"
-- ,"./Shake webmanpages # generate individual web man pages as markdown"
-- ,"./Shake webmanall # generate all-in-one web manual as markdown"
,"./Shake site/doc/VERSION/.snapshot # generate a versioned snapshot of the web manuals"
,""
,"./Shake site/doc/VERSION/.snapshot # save the checked-out web manuals as a versioned snapshot"
,"./Shake clean # clean generated files"
,"./Shake Clean # clean harder"
,"./Shake Clean # clean more thoroughly"
,""
,"./Shake [help] # show commands"
,"./Shake --help # show detailed Shake options, eg --color"
]
@ -85,19 +86,25 @@ main = do
phony "help" $ liftIO $ putStrLn usage
-- phony "compile" $ need ["Shake"]
--
-- "Shake" %> \out -> do
-- need [out <.> "hs"]
-- unit $ cmd "./Shake.hs" -- running as stack script installs deps and compiles
-- putLoud "You can now run ./Shake instead of ./Shake.hs"
phony "all" $ need ["manuals", "website"]
-- manuals
-- phony "compile" $ need ["Shake"]
-- "Shake" %> \out -> do
-- need [out <.> "hs"]
-- unit $ cmd "./Shake.hs" -- running as stack script installs deps and compiles
-- putLoud "You can now run ./Shake instead of ./Shake.hs"
-- MANUALS
let
manpageNames = [ -- in suggested reading order
-- documentation versions shown on the website (excluding 0.27 which is handled specially)
docversions = [ "1.0" , "1.1" , "1.2" , "1.3" , "1.4" , "1.5" , "1.9", "1.10", "1.11", "1.12" ]
-- names, files, uris:
-- man page names (manual names plus a man section number), in suggested reading order
manpageNames = [
"hledger.1"
,"hledger-ui.1"
,"hledger-web.1"
@ -108,40 +115,27 @@ main = do
,"hledger_timedot.5"
]
-- basic manual names, without numbers
manualNames = map manpageNameToManualName manpageNames
-- hledger.1 -> hledger, hledger_journal.5 -> hledger_journal
manpageNameToManualName = dropNumericSuffix
where
dropNumericSuffix s = reverse $
case reverse s of
c : '.' : cs | isDigit c -> cs
cs -> cs
-- hledger -> hledger.1, hledger_journal -> hledger_journal.5
manualNameToManpageName s
| '_' `elem` s = s <.> "5"
| otherwise = s <.> "1"
-- manuals m4 source; may include other source files (hledger/hledger.m4.md)
m4manpages = [manualDir m </> m <.> "m4.md" | m <- manualNames]
-- main markdown+m4 source files for manuals (hledger/hledger.m4.md)
-- These may include additional files using m4.
m4manuals = [manualDir m </> m <.> "m4.md" | m <- manualNames]
-- manuals rendered to nroff, ready for man (hledger/hledger.1)
nroffmanpages = [manpageDir m </> m | m <- manpageNames]
nroffmanuals = [manpageDir m </> m | m <- manpageNames]
-- manuals rendered to text, ready for embedding (hledger/hledger.txt)
txtmanpages = [manualDir m </> m <.> "txt" | m <- manualNames]
-- manuals rendered to plain text, ready for embedding (hledger/hledger.txt)
txtmanuals = [manualDir m </> m <.> "txt" | m <- manualNames]
-- manuals rendered to info, ready for info (hledger/hledger.info)
infomanpages = [manualDir m </> m <.> "info" | m <- manualNames]
infomanuals = [manualDir m </> m <.> "info" | m <- manualNames]
-- manuals rendered to markdown, ready for web output by pandoc (site/hledger.md)
webmanpages = ["site" </> manpageNameToUri m <.> "md" | m <- manpageNames]
-- manuals rendered to markdown, ready for conversion to html (site/hledger.md)
webmanuals = ["site" </> manpageNameToUri m <.> "md" | m <- manpageNames]
-- versions of documentation (excluding 0.27)
docversions = [ "1.0" , "1.1" , "1.2" , "1.3" , "1.4" , "1.5" , "1.9", "1.10", "1.11", "1.12" ]
-- manuals rendered to html by pandoc
-- website html pages - all manual versions plus misc pages in site/ or copied from elsewhere.
-- All these names will have lower-case URIs on the website.
webhtmlpages
= map (normalise . ("site/_site" </>))
$ ( [ prefix </> manpageNameToUri mPage <.> "html"
@ -164,41 +158,43 @@ main = do
)
-- manuals rendered to markdown and combined, ready for web rendering
webmanall = "site/manual.md"
webmancombined = "site/manual.md"
-- file extensions which should just be copied directly over to the website
webcopyfileexts = ["png", "gif", "cur", "js", "css", "eot", "ttf", "woff", "svg"]
-- extensions of static web asset files, to be copied to the website
webassetexts = ["png", "gif", "cur", "js", "css", "eot", "ttf", "woff", "svg"]
-- The directory in which to find this man page.
-- hledger.1 -> hledger/doc, hledger_journal.5 -> hledger-lib/doc
manpageDir m
| '_' `elem` m = "hledger-lib"
| otherwise = dropExtension m
-- The directory in which to find this manual.
-- hledger -> hledger, hledger_journal -> hledger-lib
manualDir m
| '_' `elem` m = "hledger-lib"
| otherwise = m
-- The URI corresponding to this man page.
-- hledger.1 -> hledger, hledger_journal.5 -> journal
manpageNameToUri m | "hledger_" `isPrefixOf` m = dropExtension $ drop 8 m
| otherwise = dropExtension m
-- The man page corresponding to this URI.
-- hledger -> hledger.1, journal -> hledger_journal.5
manpageUriToName u | "hledger" `isPrefixOf` u = u <.> "1"
| otherwise = "hledger_" ++ u <.> "5"
-- Generate the manuals in nroff, plain text and info formats.
phony "manuals" $ do
need $
nroffmanpages
++ infomanpages
++ txtmanpages
nroffmanuals
++ infomanuals
++ txtmanuals
-- man pages
-- use m4 and pandoc to process macros, filter content, and convert to nroff suitable for man output
phony "manpages" $ need nroffmanpages
nroffmanpages |%> \out -> do -- hledger/hledger.1
-- Generate nroff man pages suitable for man output.
phony "manmanuals" $ need nroffmanuals
nroffmanuals |%> \out -> do -- hledger/hledger.1
let src = manpageNameToManualName out <.> "m4.md"
lib = "doc/lib.m4"
dir = takeDirectory out
@ -214,18 +210,17 @@ main = do
"--lua-filter tools/pandoc-drop-links.lua"
"-o" out
-- render man page nroffs to fixed-width text for embedding in executables, with nroff
phony "txtmanpages" $ need txtmanpages
txtmanpages |%> \out -> do -- hledger/hledger.txt
-- Generate plain text manuals suitable for embedding in
-- executables and viewing with a pager.
phony "txtmanuals" $ need txtmanuals
txtmanuals |%> \out -> do -- hledger/hledger.txt
let src = manualNameToManpageName $ dropExtension out
need [src]
cmd Shell groff "-t -e -mandoc -Tascii" src "| col -bx >" out -- http://www.tldp.org/HOWTO/Man-Page/q10.html
-- use m4 and pandoc to process macros, filter content, and convert to info, suitable for info viewing
phony "infomanpages" $ need infomanpages
infomanpages |%> \out -> do -- hledger/hledger.info
-- Generate Info manuals suitable for viewing with info.
phony "infomanuals" $ need infomanuals
infomanuals |%> \out -> do -- hledger/hledger.info
let src = out -<.> "m4.md"
lib = "doc/lib.m4"
dir = takeDirectory out
@ -241,15 +236,13 @@ main = do
"-t texinfo |"
makeinfo "--force --no-split -o" out
-- web site
phony "website" $ do
need $ [ "website-copy" , "website-render" ]
-- WEBSITE MARKDOWN SOURCE
-- use m4 and pandoc to process macros and filter content, leaving markdown suitable for web output
phony "webmanpages" $ need webmanpages
webmanpages |%> \out -> do -- site/hledger.md
-- Generate the individual web manuals' markdown source, using m4
-- and pandoc to tweak content.
phony "webmanuals" $ need webmanuals
webmanuals |%> \out -> do -- site/hledger.md
let manpage = manpageUriToName $ dropExtension $ takeFileName out -- hledger
manual = manpageNameToManualName manpage
dir = manpageDir manpage
@ -269,47 +262,43 @@ main = do
"--lua-filter tools/pandoc-demote-headers.lua"
">>" out
-- adjust and combine man page mds for single-page web output, using pandoc
phony "webmanall" $ need [ webmanall ]
webmanall %> \out -> do
need webmanpages
liftIO $ writeFile webmanall "\\$toc\\$" -- # Big Manual\n\n -- TOC style is better without main heading,
forM_ webmanpages $ \f -> do -- site/hledger.md, site/journal.md
cmd Shell ("printf '\\n\\n' >>") webmanall :: Action ExitCode
-- Generate the combined web manual's markdown source, by
-- concatenating tweaked versions of the individual manuals.
phony "webmancombined" $ need [ webmancombined ]
webmancombined %> \out -> do
need webmanuals
liftIO $ writeFile webmancombined "\\$toc\\$" -- # Big Manual\n\n -- TOC style is better without main heading,
forM_ webmanuals $ \f -> do -- site/hledger.md, site/journal.md
cmd Shell ("printf '\\n\\n' >>") webmancombined :: Action ExitCode
cmd Shell pandoc f "-t markdown-fenced_divs --atx-headers"
"--lua-filter tools/pandoc-drop-toc.lua"
"--lua-filter tools/pandoc-demote-headers.lua"
">>" webmanall :: Action ExitCode
">>" webmancombined :: Action ExitCode
-- adjust and combine recipe mds for single-page web output, using pandoc
-- build the currently checked out web docs and save as a named snapshot
"site/doc/*/.snapshot" %> \out -> do
need [ webmanall ]
let snapshot = takeDirectory out
cmd Shell "mkdir -p" snapshot :: Action ExitCode
forM_ webmanpages $ \f -> do -- site/hledger.md, site/journal.md
cmd Shell "cp" f (snapshot </> takeFileName f) :: Action ExitCode
cmd Shell "cp" "site/manual.md" snapshot :: Action ExitCode
cmd Shell "cp -r site/images" snapshot :: Action ExitCode
cmd Shell "touch" out -- :: Action ExitCode
phony "website-copy" $ do
orig_files <- getDirectoryFiles "site" (map ("//*" <.>) webcopyfileexts)
-- WEBSITE HTML & ASSETS
phony "website" $ need $ [ "webassets" , "webhtml" ]
-- copy all static asset files (files with certain extensions
-- found under sites, plus one or two more) to sites/_site/
phony "webassets" $ do
assets <- getDirectoryFiles "site" (map ("//*" <.>) webassetexts)
need [ "site/_site" </> file
| file <-
"files/README" :
orig_files
| file <- assets ++ [
"files/README"
]
, not ("_site//*" ?== file)
]
phony "website-render" $ do
need webhtmlpages
-- copy any one of the static asset files to sites/_site/
"site/_site/files/README" : [ "site/_site//*" <.> ext | ext <- webassetexts ] |%> \out -> do
copyFile' ("site" </> dropDirectory2 out) out
"site/_site/files/README" : [ "site/_site//*" <.> ext | ext <- webcopyfileexts ] |%> \out -> do
let input = "site" </> dropDirectory2 out
copyFile' input out
-- render all website pages as html, saved in sites/_site/
phony "webhtml" $ need webhtmlpages
-- render one website page as html, saved in sites/_site/
"site/_site//*.html" %> \out -> do
let source = "site" </> dropDirectory2 out -<.> "md"
pageTitle = takeBaseName out
@ -323,12 +312,26 @@ main = do
"--lua-filter" "tools/pandoc-site.lua"
"--output" out
-- cleanup
-- MISC
-- Generate the web manuals based on the current checkout and save
-- them as the specified versioned snapshot in site/doc/VER/ .
-- .snapshot is a dummy file.
"site/doc/*/.snapshot" %> \out -> do
need $ webmancombined : webmanuals
let snapshot = takeDirectory out
cmd Shell "mkdir -p" snapshot :: Action ExitCode
forM_ webmanuals $ \f -> do -- site/hledger.md, site/journal.md
cmd Shell "cp" f (snapshot </> takeFileName f) :: Action ExitCode
cmd Shell "cp" "site/manual.md" snapshot :: Action ExitCode
cmd Shell "cp -r site/images" snapshot :: Action ExitCode
cmd Shell "touch" out -- :: Action ExitCode
phony "clean" $ do
putNormal "Cleaning generated files"
removeFilesAfter "." webmanpages
removeFilesAfter "." [webmanall]
removeFilesAfter "." webmanuals
removeFilesAfter "." [webmancombined]
phony "Clean" $ do
need ["clean"]
@ -341,5 +344,20 @@ main = do
removeFilesAfter ".shake" ["//*"]
-- Convert numbered man page names to manual names.
-- hledger.1 -> hledger, hledger_journal.5 -> hledger_journal
manpageNameToManualName = dropNumericSuffix
where
dropNumericSuffix s = reverse $
case reverse s of
c : '.' : cs | isDigit c -> cs
cs -> cs
-- Convert manual names to numbered man page names.
-- hledger -> hledger.1, hledger_journal -> hledger_journal.5
manualNameToManpageName s
| '_' `elem` s = s <.> "5"
| otherwise = s <.> "1"
dropDirectory2 = dropDirectory1 . dropDirectory1