[Haskell-cafe] Documenting Examples for a library

[Guru Devanla]

Hello,

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:
https://hackage.haskell.org/package/pptable-0.2.0.0/docs/Text-PrettyPrint-Tabulate-Example.html.


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:
    Saw: ‘Main’
    Expected: ‘Text.PrettyPrint.Tabulate.Example’

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.

Thanks
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20180315/fcf0df5d/attachment.html>