A good way of documenting packages is one of the biggest gaps in the julia ecosystem right now. Part of the reason why is evinced in the issues you cite: no matter what the system is, someone is going to hate it. At this point, I'm sort of hoping someone will just ignore all feedback and build whatever they want.
That said, I think this is a pretty elegant solution. Just relying on markdown h1 and h2 headers leaves open the possibility of generating html documentation from the same source. That's something I appreciate, since I'd also want to generate html docs with example plots rendered for gadfly. With Jake Bolewski's julia parser, I hope it will become easier to extract documentation from source code, either from comments or something like docstrings. Have you given any though to that? On Thu, Jun 5, 2014, at 03:13 PM, Michael Hatherly wrote: Hi all, I've just put up a rough prototype for package documentation at [1]https://github.com/MichaelHatherly/Docile.jl. This is not meant to be a solution to the documentation problem, but rather to start some fresh discussion on the matter. Any feedback would be great. There's more details in the readme. Regards, Mike References 1. https://github.com/MichaelHatherly/Docile.jl
