summaryrefslogtreecommitdiff
path: root/src/Doc.lhs
blob: 2f787d80e861110fd3a7d6bdbecc6065ea2be488 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
Building documentation
++++++++++++++++++++++

.. class:: nodoc

> {-# LANGUAGE OverloadedStrings #-}
> import Text.Pandoc
> import Text.Pandoc.Error (handleError)
> import Text.Highlighting.Kate.Styles (tango)
> import Data.List (stripPrefix)
> import System.FilePath (replaceFileName)
> import qualified Data.Set as S

The HTML documentation is generated directly from the source code of
Codec.Pesto by running ``cabal run pesto-doc``. 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
directly, emulate it by recursively replacing all lines starting with ``..
include::`` with the referenced file’s contents.

> readWithInclude f = do
> 	c <- readFile f
> 	let l = lines c
> 	linc <- mapM (\line -> case stripPrefix ".. include:: " line of
>		Just incfile -> readWithInclude $ replaceFileName f incfile
>		Nothing -> return line) l
> 	return $ unlines linc

The resulting string is parsed as literate Haskell with restructuredText markup.

> readDoc = readRST def {
> 	  readerExtensions = S.fromList [
> 		  Ext_literate_haskell
> 		, Ext_implicit_header_references
> 		]
> 	, readerStandalone = True }

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
> 	, writerHtml5 = True
> 	, writerHighlight = True
> 	, writerHighlightStyle = tango
>	, writerNumberSections = True
> 	, writerSectionDivs = True
> 	, writerTabStop = 4
> 	, writerHTMLMathMethod = MathJax "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
> 	, writerVariables = [("css", "pesto.css"), ("lang", "en")]
> 	}