Yes, using Markdown.jl was my first though. Since it's lacking the h2 header and I wanted to just push on ahead I avoided it. Having the REPL formatted like this would be wonderful. I'll have a look at dumping to string like this shortly (or tomorrow).
On Sunday, 8 June 2014 22:45:04 UTC+2, Mike Innes wrote: > > Thinking about it, it'd make a lot of sense if you did pass the doc > strings through Markdown.jl. You'd get the nice formatting for free – just > render the markdown to a string (it will have ANSI codes for formatting) > and store that in the database instead of the raw text. This is something > we want to have eventually so it'd be really cool to see it prototyped. I > just tried it out on docile.md and it works fine – it doesn't support > second-level headers just yet so you'll need to keep your splitting by > header step for now, but in the future you could just walk the parse tree. > > [image: Inline images 2] > > The hash-bang syntax for an annotation is a good idea. The only thing to > note is that we want to output documentation to an interactive IJulia > format, which won't support things like sandboxes. I'm also going to do > something with splicing syntax, $(...). > > > On 8 June 2014 21:08, Michael Hatherly <michael...@gmail.com <javascript:> > > wrote: > >> Not much parsing currently. I'm busy trying to simplify things to rely >> only on H1 (current module) and H2 (function/macro/const) markdown headers >> for separation (seems to be working fine). >> For code blocks in documentation I'm planning on just using standard >> non-highlighting indent ones -- not fenced code blocks for simplicity. To >> decide whether to run the code or not I'm thinking of some kind of special >> comment in each code block something like >> >> #! run hide in.ex1 >> julia> a = rand(3,3) >> >> The #! comment line would be hidden when outputting the documentation. >> Commands such as `run` to execute (not run by default) the code block, >> `hide` to suppress (shown default) output and `in.*` to specify a sandbox >> module to eval in so that you can reuse variables between different >> examples. New sandboxes would be created for each code block by default to >> avoid clashing variables. >> Code blocks could be either script- or REPL-style (with a julia>). REPL >> ones would behave like the julia REPL as far as possible. Script style >> blocks would output their final values. Blacklisting some functions should >> probably be done as well. >> I'm thinking that this would probably be a separate package. >> >> >> On Sunday, 8 June 2014 21:27:30 UTC+2, Mike Innes wrote: >>> >>> 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 >>>>> >>>>> >
