From 99f52f719af5b89c8f0b9bb95110ede0a40e82ea Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 4 Jan 2017 16:17:39 -0800 Subject: [PATCH] site: new system for generating versioned docs --- Shake.hs | 58 ++++++++++++++++++++++++--------------------- doc/lib.m4 | 19 ++++++++------- doc/manual0.27.diff | 11 --------- site/.gitignore | 3 ++- site/README | 2 +- site/doc/README | 5 ++++ site/js/site.js | 24 +++++++++++++++---- 7 files changed, 70 insertions(+), 52 deletions(-) delete mode 100644 doc/manual0.27.diff create mode 100644 site/doc/README diff --git a/Shake.hs b/Shake.hs index 47b1ec927..10ce15488 100755 --- a/Shake.hs +++ b/Shake.hs @@ -53,14 +53,15 @@ usage = unlines ["Usage:" ,"./Shake.hs # compile this script" ,"./Shake # show commands" + ,"./Shake docs # generate built-in manuals (plaintext, man, info)" + ,"./Shake website # generate the web site (web manuals, web pages)" +-- ,"./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 for hakyll" +-- ,"./Shake webmanall # generate all-in-one web manual for hakyll" + ,"./Shake site/doc/VER/.snapshot # generate and save a versioned web site snapshot" ,"./Shake all # generate everything" - ,"./Shake docs # generate general docs" - ,"./Shake website # generate the web site" - ,"./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 web man pages for hakyll" - ,"./Shake webmanual # generate combined web man page for hakyll" ,"./Shake clean # clean generated files" ,"./Shake Clean # clean harder" ,"./Shake --help # show options, eg --color" @@ -93,8 +94,7 @@ main = do -- -- "Shake" %> \out -> do -- need [out <.> "hs"] --- unit $ cmd "./Shake.hs --version" -- install libs via shebang line --- unit $ cmd "stack ghc Shake.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 ["docs", "website"] @@ -123,7 +123,7 @@ main = do -- manuals rendered to markdown, ready for web output by hakyll (site/hledger.md) webmanpages = ["site" manpageNameToUri m <.>"md" | m <- manpageNames] -- manuals rendered to markdown and combined, ready for web output by hakyll - webmanual = "site/manual.md" + webmanall = "site/manual.md" -- hledger.1 -> hledger/doc, hledger_journal.5 -> hledger-lib/doc manpageDir m @@ -208,11 +208,12 @@ main = do phony "website" $ do need $ webmanpages ++ - [webmanual - ,"releasemanual" + [webmanall ,hakyllstd ] cmd Shell (Cwd "site") "hakyll-std/hakyll-std" "build" + -- website also links to old manuals, which are generated manually + -- with ./Shake websnapshot and committed -- use m4 and pandoc to process macros and filter content, leaving markdown suitable for web output phony "webmanpages" $ need webmanpages @@ -239,29 +240,30 @@ main = do ">>" out -- adjust and combine man page mds for single-page web output, using pandoc - phony "webmanual" $ need [ webmanual ] + phony "webmanall" $ need [ webmanall ] - webmanual %> \out -> do + webmanall %> \out -> do need webmanpages - liftIO $ writeFile webmanual "* toc\n\n" + liftIO $ writeFile webmanall "* toc\n\n" forM_ webmanpages $ \f -> do -- site/hledger.md, site/journal.md - cmd Shell ("printf '\\n\\n' >>") webmanual :: Action ExitCode + cmd Shell ("printf '\\n\\n' >>") webmanall :: Action ExitCode cmd Shell "pandoc" f "-t markdown --atx-headers" -- "--filter doc/pandoc-drop-man-blocks" "--filter doc/pandoc-drop-toc" -- "--filter doc/pandoc-capitalize-headers" "--filter doc/pandoc-demote-headers" - ">>" webmanual :: Action ExitCode - - -- check out and render manual pages for the current release also - phony "releasemanual" $ need [ "releasemanual0.27" ] - - phony "releasemanual0.27" $ do - -- XXX under doc so hakyll-std will render it - cmd "mkdir -p site/doc/0.27" :: Action ExitCode - cmd Shell "git show 0.27:doc/manual.md >site/doc/0.27/manual.md" :: Action ExitCode - cmd Shell "patch site/doc/0.27/manual.md doc/manual0.27.diff " + ">>" webmanall :: Action ExitCode + -- 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 -- build standard hakyll script used for site rendering hakyllstd %> \out -> do @@ -281,7 +283,9 @@ main = do phony "clean" $ do putNormal "Cleaning generated files" removeFilesAfter "." webmanpages - removeFilesAfter "." [webmanual] + removeFilesAfter "." [webmanall] + -- removeFilesAfter "." ["site/doc/[0-9]*"] + cmd Shell "rm -rf site/doc/[0-9]*" phony "Clean" $ do need ["clean"] diff --git a/doc/lib.m4 b/doc/lib.m4 index f44ee0ca3..50f87d9a8 100644 --- a/doc/lib.m4 +++ b/doc/lib.m4 @@ -14,16 +14,19 @@ m4_dnl Links to dev and recent release versions of a manual. m4_dnl $1 is the manual's web slug: hledger, hledger-ui, journal, csv etc. m4_dnl The current version is hidden (or whatever) by highlightDocVersion in site.js. m4_dnl -m4_define({{_docversionlinks_}}, -
+m4_define({{_docversionlinks_}},m4_dnl This doc is for version **_version_**. -Available versions: -_version_ -| 1.0 -| 0.27 -
)m4_dnl +m4_dnl +m4_dnl Too painful for static generation, insert from site.js instead +m4_dnl Available versions: +m4_dnl dev +m4_dnl | 1.1 +m4_dnl | 1.0 +m4_dnl | 0.27 +)m4_dnl m4_dnl -m4_define({{_toc_}}, {{* toc}})m4_dnl +m4_define({{_toc_}},{{ +* toc}})m4_dnl m4_dnl m4_dnl _table_({{ m4_dnl | cell1 | cell2 ... diff --git a/doc/manual0.27.diff b/doc/manual0.27.diff deleted file mode 100644 index fdb541cfd..000000000 --- a/doc/manual0.27.diff +++ /dev/null @@ -1,11 +0,0 @@ -4a4,5 -> -> -6a7,12 ->
-> This doc is for version **0.27**. -> Available versions: -> 1.0 -> | 0.27 ->
-> diff --git a/site/.gitignore b/site/.gitignore index 8cefb0e50..c7d2df421 100644 --- a/site/.gitignore +++ b/site/.gitignore @@ -12,4 +12,5 @@ journal.md timeclock.md timedot.md manual.md -[0-9].* \ No newline at end of file +[0-9].* +.snapshot \ No newline at end of file diff --git a/site/README b/site/README index 0c0f3305b..3bdfd5749 100644 --- a/site/README +++ b/site/README @@ -2,4 +2,4 @@ Static bits of the hledger.org website. In some cases these are rendered to _site/* by hakyll (via the hakyll-std script), in others they are served directly from the git -working copy. +working copy. (?) diff --git a/site/doc/README b/site/doc/README new file mode 100644 index 000000000..9e5c65772 --- /dev/null +++ b/site/doc/README @@ -0,0 +1,5 @@ +Snapshots of past versions of the web content. +These are in the "doc/" subdirectory so that hakyll-std will see them. +At each release, a new snapshot should be generated and committed. +Major releases should also be added to the "available +versions" links in site.js. diff --git a/site/js/site.js b/site/js/site.js index c8d56c6f2..14df73a72 100644 --- a/site/js/site.js +++ b/site/js/site.js @@ -1,12 +1,28 @@ $(document).ready( function() { - highlightDocVersion(); + addDocVersions(); + highlightCurrentDocVersion(); }); -function highlightDocVersion() { - $('.versions').each( function() { +function addDocVersions() { + var parts = window.location.pathname.split('/'); + var page = parts.length > 0 ? parts[parts.length-1].slice(0,-5) : ''; + var hash = window.location.hash.slice(1); + var topic = (page=='manual' && hash) ? hash : page; + var newhash = (page=='manual' && topic!='manual') ? ('#'+topic) : ''; + var newpage = page=='manual' ? page : topic; + $('.docversions').html('Available versions: \ +dev \ +| 1.1 \ +| 1.0 \ +| 0.27 \ +'); +} + +function highlightCurrentDocVersion() { + $('.docversions').each( function() { var parts = window.location.pathname.split('/'); var dir = parts.length > 1 ? parts[parts.length-2] : ''; - var ver = $.isNumeric(dir) ? dir : '1.1'; + var ver = $.isNumeric(dir) ? dir : 'dev'; $(this).find('a').each( function() { if ($(this).html() == ver) $(this)