;site: Merge the new sphinx-based website.

See related commit in the site repo. [ci skip]
2019-08-30 07:57:41 -07:00 · 2019-08-30 07:57:41 -07:00 · f57c6777cd
commit f57c6777cd
parent 4a5b4142e1 65692b0e36
16 changed files with 64 additions and 98 deletions
--- a/.gitignore
+++ b/.gitignore
@ -82,3 +82,4 @@ hledger-web/yesod-devel/
 *.spk

 # recent stuff
+site
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -1,6 +1,3 @@
-<!-- consolidating dev docs from wiki, https://github.com/simonmichael/hledger/issues/920 WIP -->
-$TOC$
-
 <style>
 /* table styles */
 tr.even { background-color:#eee;}
@ -9,8 +6,6 @@ th, td  {white-space:nowrap;}

 # Contributor Guide

-<br clear=all>
-
 ## Quick Links

 | | |
@ -202,7 +197,7 @@ express gratitude,
 build prosperity consciousness,
 and help transform world finance!

- Use the donate links on the [home page](/)
+- Use the donate links on the [home page](https://hledger.org)
 - Configure a recurring donation
 - Contribute or pledge bounties on issues you care about
 - Ask your organization to contribute
@ -699,7 +694,7 @@ About testing in the hledger project, as of 201809.

    Here\'s the pattern (let us know if you see a better way):

-    ``` {.haskell}
+    ``` haskell
    module Foo (
      ...
      tests_Foo -- export this module's and submodules' tests
@ -841,19 +836,19 @@ tests, at least. It would be useful to set this up for hledger.

 Run unit tests:

-``` {.example}
+``` example
 $ make unittest
 ```

 Run doctests:

-``` {.example}
+``` example
 $ make doctest
 ```

 Run functional tests (and unit tests, now):

-``` {.example}
+``` example
 $ stack install shelltestrunner
 $ make functest
 ```
@ -861,37 +856,37 @@ $ make functest
 Run the package tests (unit tests, maybe doctests, but not functional
 tests) of all or selected packages.

-``` {.example}
+``` example
 $ stack test [PKG]
 ```

 Run \"default tests: package plus functional tests\":

-``` {.example}
+``` example
 $ make test
 ```

 Test generation of haddock docs:

-``` {.example}
+``` example
 $ make haddocktest
 ```

 Thorough test for build issues with current GHC:

-``` {.example}
+``` example
 $ make buildtest
 ```

 Thorough test for build issues with all supported GHC versions:

-``` {.example}
+``` example
 $ make buildtestall
 ```

 Run built-in hledger/hledger-lib unit tests via hledger command:

-``` {.example}
+``` example
 $ hledger test  # test installed hledger
 $ stack build hledger && stack exec -- hledger test  # test just-built hledger
 $ hledger test --help
@ -908,19 +903,19 @@ test [TESTPATTERN] [SEED]

 Rebuild and rerun hledger/hledger-lib unit tests via ghcid:

-``` {.example}
+``` example
 $ make ghcid-test
 ```

 Rebuild and rerun only some tests via ghcid (see hledger test --help):

-``` {.example}
+``` example
 $ make ghcid-test-TESTPATTERN
 ```

 See all test-related make rules:

-``` {.example}
+``` example
 $ make help-test
 ```

@ -1516,7 +1511,7 @@ If you're new to this process, [help.github.com](http://help.github.com) may be

 ### Add yourself to the contributor list

- after getting something into the master branch, read and sign the [contributor list & agreement](contributors.html). Or, [ask](/docs.html#helpfeedback) to be added.
+- after getting something into the master branch, read and sign the [contributor list & agreement](https://hledger.org/contributors.html). Or, [ask](/index.html#help-feedback) to be added.
 - give yourself a high five!

 ### Work on docs
--- a/4
+++ b/4
@ -776,8 +776,10 @@ site: \
 		&& echo 'Please run "make Shake" first (manual compilation of Shake.hs is required)' \
 		|| ( \
 			echo; \
-			./Shake hledgerorg -VV \
+			./Shake hledgerorg -VV; \
+			make -C site html; \
 		) 2>&1 | tee -a site.log
+#     ^ running both shake and sphinx for now

 ###############################################################################
 $(call def-help-subheading,RELEASING:)
--- a/Shake.hs
+++ b/Shake.hs
@ -113,7 +113,11 @@ sed      = "sed -E"
 fromsrcmd = "-f markdown-smart-tex_math_dollars"

 -- The kind of markdown we like to generate for the website.
-towebmd = "-t markdown-smart-fenced_divs --atx-headers"
+-- This will be consumed by sphinx extensions:
+--  recommonmark (Commonmark syntax, https://spec.commonmark.org)
+--  sphinx-markdown-tables (PHP Markdown Extra table syntax, https://michelf.ca/projects/php-markdown/extra/#table)
+-- XXX trying to force the use of pipe_tables here, but sometimes it uses html instead
+towebmd = "-t markdown-smart-fenced_divs-fenced_code_attributes-simple_tables-multiline_tables-grid_tables --atx-headers"


 main = do
@ -208,7 +212,7 @@ main = do
      mdmanuals = ["site" </> manpageNameToUri m <.> "md" | m <- manpageNames]

      -- latest version of the manuals rendered to html
-      htmlmanuals = ["site/_site" </> manpageNameToUri m <.> "html" | m <- manpageNames++["manual"]]
+      htmlmanuals = ["site/_site" </> manpageNameToUri m <.> "html" | m <- manpageNames]

      -- old versions of the manuals rendered to html
      oldhtmlmanuals = map (normalise . ("site/_site/doc" </>) . (<.> "html")) $
@ -220,9 +224,6 @@ main = do

      -- TODO: make website URIs lower-case ?

-      -- manuals rendered to markdown and combined, ready for web rendering
-      mdcombinedmanual = "site/manual.md"
-
      -- extensions of static web asset files, to be copied to the website
      webassetexts = ["png", "gif", "cur", "js", "css", "eot", "ttf", "woff", "svg"]

@ -334,19 +335,6 @@ main = do
        "--lua-filter tools/pandoc-demote-headers.lua"
        ">>" out

-    -- Generate the combined web manual's markdown source, by
-    -- concatenating tweaked versions of the individual manuals.
-    phony "mdcombinedmanual" $ need [ mdcombinedmanual ]
-    mdcombinedmanual %> \out -> do
-      need mdmanuals
-      liftIO $ writeFile mdcombinedmanual $ addToc ""
-      forM_ mdmanuals $ \f -> do -- site/hledger.md, site/journal.md
-        cmd_ Shell ("printf '\\n\\n' >>") mdcombinedmanual
-        cmd_ Shell pandoc f towebmd
-          "--lua-filter tools/pandoc-drop-toc.lua"
-          "--lua-filter tools/pandoc-demote-headers.lua"
-          ">>" mdcombinedmanual
-
    -- Copy some extra markdown files from the main repo into the site
    -- TODO adding table of contents placeholders
    [
@ -392,7 +380,6 @@ main = do

    -- Render one website page as html, saved in sites/_site/.
    -- Github-style wiki links will be hyperlinked.
-    -- The download page will have a TOC placeholder prepended.
    "site/_site//*.html" %> \out -> do
        let filename = takeBaseName out
            pagename = fileNameToPageName filename
@ -403,16 +390,13 @@ main = do
              | otherwise   = "site" </> filename <.> "md"
            template = "site/site.tmpl"
            siteRoot = if "site/_site/doc//*" ?== out then "../.." else "."
-            maybeAddToc | isdownloadpage = addToc
-                        | otherwise      = id
        need [source, template]
-        -- read markdown source, link any wikilinks, maybe add a heading and TOC, pipe it to pandoc, write html out
-        Stdin . wikiLink . maybeAddToc <$> (readFile' source) >>=
+        -- read markdown source, link any wikilinks, pipe it to pandoc, write html out
+        Stdin . wikiLink <$> (readFile' source) >>=
          (cmd Shell pandoc "-" fromsrcmd "-t html"
                           "--template" template
                           ("--metadata=siteRoot:" ++ siteRoot)
                           ("--metadata=\"title:" ++ pagename ++ "\"")
-                           "--lua-filter=tools/pandoc-toc.lua"
                           "-o" out )

    -- This rule, for updating the live hledger.org site, gets called by:
@ -662,12 +646,11 @@ main = do
    -- them as the specified versioned snapshot in site/doc/VER/ .
    -- .snapshot is a dummy file.
    "site/doc/*/.snapshot" %> \out -> do
-      need $ mdcombinedmanual : mdmanuals
+      need mdmanuals
      let snapshot = takeDirectory out
      cmd_ Shell "mkdir -p" snapshot
      forM_ mdmanuals $ \f -> -- site/hledger.md, site/journal.md
        cmd_ Shell "cp" f (snapshot </> takeFileName f)
-      cmd_ Shell "cp" "site/manual.md" snapshot
      cmd_ Shell "cp -r site/images" snapshot
      cmd_ Shell "touch" out

@ -678,7 +661,6 @@ main = do
      -- removeFilesAfter "." commandtxts
      putNormal "Cleaning generated manuals, staged site content"
      removeFilesAfter "." mdmanuals
-      removeFilesAfter "." [mdcombinedmanual]
      removeFilesAfter "." [
        -- "site/README.md",
        -- "site/CONTRIBUTING.md"
@ -727,11 +709,6 @@ type Markdown = String
 addHeading :: String -> Markdown -> Markdown
 addHeading h = (("# "++h++"\n\n")++)

-- | Prepend a table of contents placeholder.
-addToc :: Markdown -> Markdown
-addToc = ((tocMarker++"\n\n")++)
-  where tocMarker = "$TOC$"
-
 -- | Convert Github-style wikilinks to hledger website links.
 wikiLink :: Markdown -> Markdown
 wikiLink =
--- a/doc/common.m4
+++ b/doc/common.m4
@ -28,13 +28,9 @@ This doc is for version **_version_**
 m4_dnl comment (dev) for releases, uncomment between releases:
 m4_dnl (dev)
 .
-<span class="docversions">m4_dnl
-</span>)m4_dnl
-m4_dnl
-m4_dnl Insert a table of contents marker, which doc build scripts will populate.
-m4_define({{_toc_}},{{
-\$TOC\$
-}})m4_dnl
+m4_dnl <span class="docversions">m4_dnl
+m4_dnl </span>
+)m4_dnl
 m4_dnl
 m4_dnl Helpers for generating table markup.
 m4_dnl _table_({{
--- a/hledger-api/hledger-api.m4.md
+++ b/hledger-api/hledger-api.m4.md
@ -4,7 +4,6 @@

 _web_({{
 _docversionlinks_({{hledger-api}})
-_toc_
 }})

 _man_({{
--- a/hledger-lib/hledger_csv.m4.md
+++ b/hledger-lib/hledger_csv.m4.md
@ -4,7 +4,6 @@

 _web_({{
 _docversionlinks_({{csv}})
-_toc_
 }})
 _man_({{

@ -107,22 +106,22 @@ you'll need to specify the format.
 DATEFMT is a [strptime-like date parsing pattern](http://hackage.haskell.org/packages/archive/time/latest/doc/html/Data-Time-Format.html#v:formatTime),
 which must parse the date field values completely. Examples:

-``` {.rules .display-table}
+``` rules
 # for dates like "11/06/2013":
 date-format %m/%d/%Y
 ```

-``` {.rules .display-table}
+``` rules
 # for dates like "6/11/2013" (note the - to make leading zeros optional):
 date-format %-d/%-m/%Y
 ```

-``` {.rules .display-table}
+``` rules
 # for dates like "2013-Nov-06":
 date-format %Y-%h-%d
 ```

-``` {.rules .display-table}
+``` rules
 # for dates like "11/6/2013 11:32 PM":
 date-format %-m/%-d/%Y %l:%M %p
 ```
@ -153,11 +152,11 @@ This sets a journal entry field (one of the standard names above) to the given t
 which can include CSV field values interpolated by name (`%CSVFIELDNAME`) or 1-based position (`%N`).
 <!-- Whitespace before or after the value is ignored. -->
 Eg:
-```{.rules .display-table}
+```rules
 # set the amount to the 4th CSV field with "USD " prepended
 amount USD %4
 ```
-```{.rules .display-table}
+```rules
 # combine three fields to make a comment (containing two tags)
 comment note: %somefield - %anotherfield, date: %1
 ```
@ -184,12 +183,12 @@ specific field).  When there are multiple patterns they can be written
 on separate lines, unindented.
 The field assignments are on separate lines indented by at least one space.
 Examples:
-```{.rules .display-table}
+```rules
 # if the CSV record contains "groceries", set account2 to "expenses:groceries"
 if groceries
 account2 expenses:groceries
 ```
-```{.rules .display-table}
+```rules
 # if the CSV record contains any of these patterns, set account2 and comment as shown
 if
 monthly service fee
--- a/hledger-lib/hledger_journal.m4.md
+++ b/hledger-lib/hledger_journal.m4.md
@ -4,7 +4,6 @@

 _web_({{
 _docversionlinks_({{journal}})
-_toc_
 }})
 _man_({{

@ -404,7 +403,7 @@ double equals sign (`== EXPECTEDBALANCE`).
 This asserts that there are no other unasserted commodities in the account 
 (or, that their balance is 0). 

-``` {.journal}
+``` journal
 2013/1/1
  a   $1
  a    1€
@ -424,7 +423,7 @@ This asserts that there are no other unasserted commodities in the account
 It's not yet possible to make a complete assertion about a balance that has multiple commodities.
 One workaround is to isolate each commodity into its own subaccount:

-``` {.journal}
+``` journal
 2013/1/1
  a:usd   $1
  a:euro   1€
--- a/hledger-lib/hledger_timeclock.m4.md
+++ b/hledger-lib/hledger_timeclock.m4.md
@ -4,7 +4,6 @@

 _web_({{
 _docversionlinks_({{timeclock}})
-_toc_
 }})
 _man_({{

@ -38,7 +37,7 @@ some number of hours to an account. Or if the session spans more than
 one day, it is split into several transactions, one for each day. For
 the above time log, `hledger print` generates these journal entries:

-``` {.shell}
+``` shell
 $ hledger -f t.timeclock print
 2015/03/30 * optional description after two spaces
    (some:account name)         0.33h
--- a/hledger-lib/hledger_timedot.m4.md
+++ b/hledger-lib/hledger_timedot.m4.md
@ -4,7 +4,6 @@

 _web_({{
 _docversionlinks_({{timedot}})
-_toc_
 }})
 _man_({{

--- a/hledger-ui/hledger-ui.m4.md
+++ b/hledger-ui/hledger-ui.m4.md
@ -4,7 +4,6 @@

 _web_({{
 _docversionlinks_({{hledger-ui}})
-_toc_
 }})

 _man_({{
@ -28,15 +27,15 @@ _web_({{
 .highslide-caption {color:white; background-color:black;}
 </style>
 <div style="float:right; max-width:200px; text-align:right;">
-<a href="images/hledger-ui/hledger-ui-sample-acc2.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc2.png" title="Accounts screen with query and depth limit" /></a>
-<a href="images/hledger-ui/hledger-ui-sample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc.png" title="Accounts screen" /></a>
-<a href="images/hledger-ui/hledger-ui-sample-acc-greenterm.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc-greenterm.png" title="Accounts screen with greenterm theme" /></a>
-<a href="images/hledger-ui/hledger-ui-sample-txn.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-txn.png" title="Transaction screen" /></a>
-<a href="images/hledger-ui/hledger-ui-sample-reg.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-reg.png" title="Register screen" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-sample-acc2.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-sample-acc2.png" title="Accounts screen with query and depth limit" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-sample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-sample-acc.png" title="Accounts screen" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-sample-acc-greenterm.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-sample-acc-greenterm.png" title="Accounts screen with greenterm theme" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-sample-txn.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-sample-txn.png" title="Transaction screen" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-sample-reg.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-sample-reg.png" title="Register screen" /></a>
 <!-- <br clear=all> -->
-<a href="images/hledger-ui/hledger-ui-bcexample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc.png" title="beancount example accounts" /></a>
-<a href="images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" title="beancount example's etrade cash subaccount" /></a>
-<a href="images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" title="beancount example's etrade investments, all commoditiess" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-bcexample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-bcexample-acc.png" title="beancount example accounts" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" title="beancount example's etrade cash subaccount" /></a>
+<a href="_static/images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" title="beancount example's etrade investments, all commoditiess" /></a>
 </div>
 }})

--- a/hledger-web/hledger-web.m4.md
+++ b/hledger-web/hledger-web.m4.md
@ -4,7 +4,6 @@

 _web_({{
 _docversionlinks_({{hledger-web}})
-_toc_
 }})

 _man_({{
@ -28,10 +27,10 @@ _web_({{
 .highslide-caption {color:white; background-color:black;}
 </style>
 <div style="float:right; max-width:200px; text-align:right;">
-<a href="images/hledger-web/normal/register.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/register.png" title="Account register view with accounts sidebar" /></a>
-<a href="images/hledger-web/normal/journal.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/journal.png" title="Journal view" /></a>
-<a href="images/hledger-web/normal/help.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/help.png" title="Help dialog" /></a>
-<a href="images/hledger-web/normal/add.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/add.png" title="Add form" /></a>
+<a href="_static/images/hledger-web/normal/register.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-web/normal/register.png" title="Account register view with accounts sidebar" /></a>
+<a href="_static/images/hledger-web/normal/journal.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-web/normal/journal.png" title="Journal view" /></a>
+<a href="_static/images/hledger-web/normal/help.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-web/normal/help.png" title="Help dialog" /></a>
+<a href="_static/images/hledger-web/normal/add.png" class="highslide" onclick="return hs.expand(this)"><img src="_static/images/hledger-web/normal/add.png" title="Add form" /></a>
 </div>
 }})

--- a/hledger/hledger.m4.md
+++ b/hledger/hledger.m4.md
@ -15,7 +15,6 @@ m4_dnl  hledger_troubleshooting.m4.md

 _web_({{
 _docversionlinks_({{hledger}})
-_toc_
 }})

 _man_({{
--- a/hledger/hledger_options.m4.md
+++ b/hledger/hledger_options.m4.md
@ -37,7 +37,7 @@ which are often a [query](#queries), filtering the data in some way.
 You can save a set of command line options/arguments in a file, one per line,
 and then reuse them by writing `@FILENAME` in a command line.
 To prevent this expansion of `@`-arguments, precede them with a `--` argument.
-For more, see [Save frequently used options](Save-frequently-used-options.html).
+For more, see [Save frequently used options](save-frequently-used-options.html).

 ## Special characters in arguments and queries

@ -168,12 +168,12 @@ but it can also be one of several other formats, listed below.
 hledger detects the format automatically based on the file extension,
 or if that is not recognised, by trying each built-in "reader" in turn:

-| Reader:         | Reads:                                                | Used for file extensions:                          
-|-----------------|-------------------------------------------------------|-------------------------------------------
-| `journal`       | hledger's journal format, also some Ledger journals   | `.journal` `.j` `.hledger` `.ledger`   
-| `timeclock`     | timeclock files (precise time logging)                | `.timeclock`                              
-| `timedot`       | timedot files (approximate time logging)              | `.timedot`                                
-| `csv`           | comma-separated values (data interchange)             | `.csv`                                    
+| Reader:     | Reads:                                              | Used for file extensions:                           |
+|-------------|-----------------------------------------------------|-----------------------------------------------------|
+| `journal`   | hledger's journal format, also some Ledger journals | `.journal` `.j` `.hledger` `.ledger`                |
+| `timeclock` | timeclock files (precise time logging)              | `.timeclock`                                        |
+| `timedot`   | timedot files (approximate time logging)            | `.timedot`                                          |
+| `csv`       | comma-separated values (data interchange)           | `.csv`                                              |

 If needed (eg to ensure correct error messages when a file has the "wrong" extension), 
 you can force a specific reader/format by prepending it to the file path with a colon. 
--- a/tools/pandoc-drop-toc.lua
+++ b/tools/pandoc-drop-toc.lua
@ -1,3 +1,4 @@
+-- Remove a $TOC$ marker (cf pandoc-toc.lua) from the document.
 function Para(p)
    if not  p.content[1]                  then return p end
    if not (p.content[1].t    == "Str")   then return p end
--- a/tools/pandoc-toc.lua
+++ b/tools/pandoc-toc.lua
@ -1,3 +1,5 @@
+-- Replace a $TOC$ marker with a table of contents generated from the document's headings.
+
 local headers = {}

 function Header(h)