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.