This is a great start as way to do external documentation – I've been thinking a lot about this problem but hadn't even considered this kind of format.
I imagine that you don't do much parsing of the markdown files except to separate entries, but I should mention that I started the Markdown.jl <https://github.com/one-more-minute/Markdown.jl> package with exactly that purpose in mind. I'm going to spend some time on it over the summer – hopefully soon we'll be able to parse documentation formats like this and display nicely formatted docs in IJulia, Light Table and even (to an extent) the REPL. Then we can start doing things like rendering inline plots, which will be really nice. I also want to have editor support for documentation (both inline and in the form of literate-julia-style files), syntax highlighting, evaluation, the whole shebang. Daniel, as far as inline documentation is concerned I've been thinking of using: """ # FFT The `fft` function computes an FFT. fft(vec) """ function fft(...)... I've been using this a little in my own code and it works nicely (haven't heard any objections yet anyway), and it's nice in that it requires no new syntax. Another option would be some kind of doc-comment marker like #|, which would take up fewer lines but would be a bit fiddlier in editors without support for it. On Sunday, 8 June 2014 17:22:52 UTC+1, Michael Hatherly wrote: > > Agreed, It's definitely a noticeable gap at the moment. What's needed > currently is a standard backend to interface with the built-in help. (My > solution is obviously not sustainable in the long term.) The syntax used to > document is, as you say, going to be disliked by some. Several different > documentation frontends with different syntaxes would be ideal, catering to > everyone's needs. (Comment blocks, external files, etc) > > I'm trying to focus as little time on the syntax, keeping it to a minimum > usable subset of markdown at the moment. I'll get a chance later next week > to do some more work on this. > > On Sunday, 8 June 2014 14:44:25 UTC+2, Daniel Jones wrote: >> >> >> 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 >> 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 >> >>
