Haddock, Cabal: How to include source code examples?

26
votes

I am the author of the operational package, which includes example code. I would like this example code to be hscolored and installed together with the API documentation, which is generated by Haddock.

I probably have to use a custom Cabal build type and create a user hook for the Haddock phase. However, I never managed to make this work. Hence, my question is:

How to include full modules as example code in Haddock?

Could you give an example of a Cabal user hook that applies hscolor to an additional source code file example.hs and joins the result with the generated Haddock documentation?

1
haskelldocumentation-generationcabalhaddock
I think this functionally needs to be added to Cabal. - Theo Belaire
It is ugly, but maybe you can try adding the examples to your Library. In that case Haddock should automatically be run on them. The overall support of Haddock/Cabal/Hackage for anything but the most basic documentation needs is still lacking at the moment. - Alessandro Vermeulen
Ah, I don't want to run Haddock on the examples, I just want to run hscolour on them, but install them whenever the user types cabal haddock. - Heinrich Apfelmus

1 Answers

2
votes

I'm a total Haskell nube and this is a shot in the dark, but couldn't you use hscolour to output the code as HTML and then do something along the lines of cabal haddock --executables --hyperlink-source to include the colorized HTML?