Just to make sure I got Docile.jl straight: It is a way to write markdown documents to document julia functions, modules, etc. After parsing it is then put into helpdb.jl, so the Base help system can access it. Further, the document is also readable as API documentation as-is, without processing.
A few thoughts: I like that the document is readable straight away on github. I think that could be a winner for many not so serious package-maintainers who can't be bothered with a separate build step for the docs. (Although sometime down the line some optional pre-processing could be good too.) I think, for a doc-system to make most people happy it needs to: 1) unify in-code and separate-file documentation 2) unify (API) documentation of Base, packages and non-packaged user code Docile could do most to (2). Maybe it would be worth having a look at http://docs.julialang.org/en/latest/stdlib/base/ and see whether docile could encode all of the information present there? A few questions: - Any ideas/thoughts on how to document methods vs functions? - The storage back-end is probably going to change someday: it could be swapped out in Docile.jl, right? - What about interaction between source and docs? Last, I think that Python or Matlab-style in-code documentation writing is important. If special syntax will be introduced, I think the doc-string should go into the function/type (or after for one-liners). Because the function/type-definition is the header of that piece of documentation. On Monday, June 9, 2014 2:58:29 PM UTC+1, Mike Innes wrote: > > writemime("text/html", md) is the best interface to use for outputting > HTML. Honestly, though, I spent about twenty minutes on HTML output so it's > going to be basic at best. Improvements are welcome, of course. > > > On 9 June 2014 13:31, Michael Hatherly <michael...@gmail.com <javascript:> > > wrote: > >> Thanks. >> >> Is Markdown.html_inline what I should be using to produce html output in >> a similar manner to terminal_print? >> >> >> On Monday, 9 June 2014 14:24:12 UTC+2, Mike Innes wrote: >> >>> This is just because Markdown.jl didn't have a release – I don't know if >>> there's a way to depend on such packages and/or arbitrary git repositories >>> (if not perhaps we should have a way?). Adding Pkg.clone("Markdown") during >>> the build step would work I guess. >>> >>> Anyway, I just pushed 0.1.0 so it should work if you re-do the build. >>> >>> >>> On 9 June 2014 13:04, Michael Hatherly <michael...@gmail.com> wrote: >>> >>>> I've managed to get it to store the markdown parsed docs now and >>>> display them correctly. Travis is complaining that it can't find Markdown >>>> though. Should I be doing something different in my REQUIRE file? >>>> >>>> >>>> On Monday, 9 June 2014 12:23:56 UTC+2, Mike Innes wrote: >>>> >>>>> Woops – yeah, terminal_print takes a columns keyword argument. >>>>> >>>>> sprint(io -> Markdown.terminal_print(io, md, columns = 80)) >>>>> >>>>> >>>>> On 9 June 2014 11:16, Michael Hatherly <michael...@gmail.com> wrote: >>>>> >>>>>> Great, just pushed some other changes so I'll look into this later >>>>>> this week. >>>>>> Having a quick look though, sprint(Markdown.terminal_print, ans) strips >>>>>> out the line wrapping. Is there an easy way to retain that formatting in >>>>>> the string? >>>>>> >>>>>> >>>>>> On Monday, 9 June 2014 10:49:56 UTC+2, Mike Innes wrote: >>>>>>> >>>>>>> I just fixed it up to work with n level headers – it should do >>>>>>> everything you need it to now. >>>>>>> >>>>>>> Just to get you started, this will render the first docstring from >>>>>>> docile.md: >>>>>>> >>>>>>> julia> Markdown.Block(Markdown.parse_file("/users/Mike/Documents/do >>>>>>> cile.md")[3:7]) >>>>>>> julia> sprint(Markdown.terminal_print, ans) >>>>>>> >>>>>>> On Sunday, 8 June 2014 22:07:40 UTC+1, Michael Hatherly wrote: >>>>>>>> >>>>>>>> So it does :) I'll have a closer look soon. >>>>>>>> >>>>>>>> On Sunday, 8 June 2014 22:29:13 UTC+2, Tim Holy wrote: >>>>>>>>> >>>>>>>>> On Sunday, June 08, 2014 01:16:51 PM Michael Hatherly wrote: >>>>>>>>> > Since everything in help is in Base as >>>>>>>>> > well, it doesn't seem to be a problem currently. >>>>>>>>> >>>>>>>>> Actually, the help system does take the module into account (I >>>>>>>>> believe Carlo >>>>>>>>> Baldassi implemented this): >>>>>>>>> >>>>>>>>> help> Base.print >>>>>>>>> Base.print(x) >>>>>>>>> >>>>>>>>> Write (to the default output stream) a canonical (un-decorated) >>>>>>>>> text representation of a value if there is one, otherwise call >>>>>>>>> "show". The representation used by "print" includes minimal >>>>>>>>> formatting and tries to avoid Julia-specific details. >>>>>>>>> >>>>>>>>> help> Profile.print >>>>>>>>> Base.Profile.print([io::IO = STDOUT], [data::Vector]; format = >>>>>>>>> :tree, C = >>>>>>>>> false, combine = true, cols = tty_cols()) >>>>>>>>> >>>>>>>>> Prints profiling results to "io" (by default, "STDOUT"). If you >>>>>>>>> do not supply a "data" vector, the internal buffer of >>>>>>>>> accumulated >>>>>>>>> backtraces will be used. "format" can be ":tree" or ":flat". >>>>>>>>> If "C==true", backtraces from C and Fortran code are shown. >>>>>>>>> "combine==true" merges instruction pointers that correspond to >>>>>>>>> the same line of code. "cols" controls the width of the >>>>>>>>> display. >>>>>>>>> >>>>>>>>> Base.Profile.print([io::IO = STDOUT], data::Vector, lidict::Dict; >>>>>>>>> format = >>>>>>>>> :tree, combine = true, cols = tty_cols()) >>>>>>>>> >>>>>>>>> Prints profiling results to "io". This variant is used to >>>>>>>>> examine >>>>>>>>> results exported by a previous call to "Profile.retrieve()". >>>>>>>>> Supply the vector "data" of backtraces and a dictionary >>>>>>>>> "lidict" of line information. >>>>>>>>> >>>>>>>>> >>>>>>>>> > I'll take another look >>>>>>>>> > when I get a chance. >>>>>>>>> > >>>>>>>>> > [1] https://github.com/JuliaLang/julia/blob/master/base/help.jl# >>>>>>>>> L102 >>>>>>>>> > >>>>>>>>> > On Sunday, 8 June 2014 21:32:36 UTC+2, Tim Holy wrote: >>>>>>>>> > > I agree with Daniel. We just need _something_, and on this >>>>>>>>> issue the >>>>>>>>> > > diversity >>>>>>>>> > > of tastes seems to make consensus impossible. So kudos to you. >>>>>>>>> I really >>>>>>>>> > > hope >>>>>>>>> > > this keeps moving forward. >>>>>>>>> > > >>>>>>>>> > > What prevents it from working with functions rather than >>>>>>>>> strings? >>>>>>>>> > > >>>>>>>>> > > --Tim >>>>>>>>> > > >>>>>>>>> > > On Saturday, June 07, 2014 02:16:11 PM 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 >>>>>>>>> > > > [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 >>>>>>>>> >>>>>>>> >>>>> >>> >
