Document format for extended Haskell examples?

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?

TIA,

Stu

1 Like

I know that opencv includes images that are automatically generated based on example code snippets in its haddock documentation, e.g.: https://hackage.haskell.org/package/opencv-0.0.2.1/docs/OpenCV-Photo.html

The code that extracts and renders the images seems to be here: https://github.com/LumiGuide/haskell-opencv/tree/master/doc

1 Like

Why make, cabal can handle that with -f options.

diagrams too has some autogenerated pictures (check source). Math: remember that haddock supports a subset of LaTeX!

Will that do?

That’s very useful – thanks.

Thanks, it sounds like Haddock is the way to go.

Stu

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.