<div dir="ltr"><div><div>Hello,<br><br>I am close to releasing a new version of  the <a href="https://hackage.haskell.org/package/pptable">https://hackage.haskell.org/package/pptable</a> 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.<br><br>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.<br><br>The approaches I have in mind to provide clear examples are as follows:<br><br>1. Provide a README.md and document all usage examples in markdown format. Allow github to produce the HTML.<br><br>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: <br><a href="https://hackage.haskell.org/package/pptable-0.2.0.0/docs/Text-PrettyPrint-Tabulate-Example.html">https://hackage.haskell.org/package/pptable-0.2.0.0/docs/Text-PrettyPrint-Tabulate-Example.html</a>. <br><br>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.<br><br></div>When I include .lhs file in a stack project, I get the following error<br></div><br><div><div><div>File name does not match module name:<br>    Saw: ‘Main’<br>    Expected: ‘Text.PrettyPrint.Tabulate.Example’<br><br>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?<br><br>Please could the group provide any recommendations and guidance on what approach I should be taking and why.<br><br>Thanks<br></div><div><br></div></div></div></div>