summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars-Dominik Braun <lars@6xq.net>2015-07-11 17:38:41 +0200
committerLars-Dominik Braun <lars@6xq.net>2015-07-11 17:38:41 +0200
commited218eeaec4d57723647a223acd2e39f068ebd53 (patch)
tree419cfff8ee0210d52868078bb12e0b440b531599
parent43242dffb867d9588bce249f02c39fe03e11aec4 (diff)
downloadpesto-ed218eeaec4d57723647a223acd2e39f068ebd53.tar.gz
pesto-ed218eeaec4d57723647a223acd2e39f068ebd53.tar.bz2
pesto-ed218eeaec4d57723647a223acd2e39f068ebd53.zip
Improve documentation documentation
-rw-r--r--src/Doc.lhs26
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