diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/Doc.lhs | 26 |
1 files changed, 16 insertions, 10 deletions
diff --git a/src/Doc.lhs b/src/Doc.lhs index 5cba5c1..0d3f1cd 100644 --- a/src/Doc.lhs +++ b/src/Doc.lhs @@ -11,16 +11,22 @@ Building documentation > import System.FilePath (replaceFileName) > import qualified Data.Set as S -The documentation is created from the source module Codec.Pesto, which includes -the other modules. We use a slightly modified template. +The HTML documentation is generated directly from the source code of +Codec.Pesto. That module serves as starting point and it includes the other +modules in a sensible order. Pandoc_ renders the restructuredText_ to HTML. We +use a slightly modified template. + +.. _pandoc: http://www.pandoc.org/ +.. _restructuredText: http://docutils.sourceforge.net/rst.html > main = do > tpl <- readFile "template.html" > doc <- readWithInclude "src/Codec/Pesto.lhs" > writeFile "_build/index.html" $ rstToHtml tpl doc -Since pandoc currently does not support restructured text’s include directive, -emulate it. +Since pandoc currently does not support restructured text’s include directive +directly, emulate it by recursively replacing all lines starting with ``.. +include::`` with the referenced file’s contents. > readWithInclude f = do > c <- readFile f @@ -30,10 +36,7 @@ emulate it. > Nothing -> return line) l > return $ unlines linc -The pass the resulting string to pandoc that builds a doctree, remove unwanted -content and build a HTML page. - -> rstToHtml tpl = writeDoc tpl . dropNoDoc . handleError . readDoc +The resulting string is parsed as literate Haskell with restructuredText markup. > readDoc = readRST def { > readerExtensions = S.fromList [ @@ -42,14 +45,17 @@ content and build a HTML page. > ] > , readerStandalone = True } -Drop blocks that should not be visible in the documentation, like module -definitions and imports. +Module definitions and imports should not be visible in the final +documentation. They are marked up with the class ``nodoc`` and removed from the +doctree before transforming it into HTML. > dropNoDoc = topDown f > where > f (Div (_, classes, _) _) | "nodoc" `elem` classes = Null > f x = x +> rstToHtml tpl = writeDoc tpl . dropNoDoc . handleError . readDoc + > writeDoc tpl = writeHtmlString def { > writerStandalone = True > , writerTemplate = tpl |