[Haskell-cafe] Documenting Examples for a library
gurudev.devanla at gmail.com
Thu Mar 15 13:23:02 UTC 2018
I am close to releasing a new version of the
https://hackage.haskell.org/package/pptable library I have been working on
off late. I am a little confused on what approach I need to take regarding
providing good documentation and working examples.
Please, note that I am not referring to the API documentation attached to
the code. For API documentation I will continue to use haddock and generate
documentation as I build.
The approaches I have in mind to provide clear examples are as follows:
1. Provide a README.md and document all usage examples in markdown format.
Allow github to produce the HTML.
2. Create and ship an Example.hs file along with library. Using a .hs file
allows haddock to build the documentation as part of the package. I took
this approach for the previous release. Here is an example:
3. Using Example.lhs. I like this approach since it lets me load the code
in ghci and test out the examples seamlessly. But, I am hitting roadblocks
with this, since I am not able to include this file as part of my stack
project. `stack haddock` fails too.
When I include .lhs file in a stack project, I get the following error
File name does not match module name:
I like (3) because I can make sure my examples run successfully, (using
stack ghci Example.lhs), before I publish them. With options (1) and (2), I
need to manually copy/past code into ghci to make sure there are no errors.
Is there a better way to do this?
Please could the group provide any recommendations and guidance on what
approach I should be taking and why.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Haskell-Cafe