I’d like to create a directory of extended examples to go with a Haskell library I’m working on. This would live in an examples directory alongside the src directory for the package.
As well as Haskell code examples I’d like to be able to include the output of Haskell code fragments (probably controlled via a Makefile). I’d also like to include images generated by the library code and a small amount of mathematical notation.
I realize this is asking a lot and I’ve been looking at Haddock, Markdown dialects, Literate Haskell files and org files.
Has anybody done these kind of extended examples and could share your approach?
Well, with one caveat for Stack users: I understand stack doesn’t have the equivalent of Cabal’s cabal haddock --executables
So I can build library documentation with Stack but need to fall back to Cabal for haddock generation for executables and tests. I’m not sure if this is a real problem yet and I should either fall back to Cabal for everything or use literate haskell.