> Yes, that's currently the scope of what it can do. Adding docs to > helpdb.jl is currently a bit hacky, but I've got some ideas regarding > that I'll sort out on Friday afternoon I think.
I think it would be helpful if Base defined a `getdoc` and `setdoc` function, adding a layer of abstraction between `help` and the underlying storage (`helpdb.jl`, `MODULE_DICT` and `FUNCTION_DICT`). Then you could just insert stuff into the appropriate `*_DICT` without monkey patching `help`. This would also decouple Docile from the unresolved backend storage problem https://github.com/JuliaLang/julia/issues/3988. > I'm not sure what the status of the storage format is. One of the core > devs will be best placed to answer something like that. Since Docile > is only in early stages right now changing things around are easy > enough. The current help format seems to work fine though for > everything I've tried so far ;) I don't think the storage format of the help entries has been discussed yet. Maybe it needs some discussion though, particularly with the issue of documenting methods vs functions. The current format can only document functions (afaik). Another thing I noted: at the moment the documentation of all packages will be loaded with importing Docile. It would be better if it only gets loaded after `using` a package. > My major motivating thought behind all this was to make the docs > as readable without processing as possible and putting package docs > on the same footing as those in base. That is a good aim. Add to that the docs in Base should eventually be based on the same method too. > Docile is using Markdown.jl for all the doc processing so producing nice > html > pages with an index (if that's kind of what you mean by pre-processing) > should be doable reasonably soon I believe. I've not done much web-related > things, but I'm sure I'll manage to get the basics going. What I meant was some "clever" stuff like, e.g., inserting method call signature automatically, checking existence, completeness, doctests and such (that is what I meant with "interaction between source and docs"). This should not be implemented right now but maybe something to keep in the back of the head. > I've had a look through the .rst files in base/doc, it uses sphinx if I'm > correct? > So Docile won't manage to do everything that it can (just yet :) Docile > should > manage most of the basic things though, but I'm sure there's noticeable > gaps in places. Converting the julia docs to Docile would be interesting to > try. I just meant the API documentation page of the standard library, not the whole of the manual. This page: http://docs.julialang.org/en/latest/stdlib/base/. I think it gets auto-generated from helpdb.jl, because the source is quite empty: https://github.com/JuliaLang/julia/blob/master/doc/stdlib/base.rst The whole manual (in Sphinx) is probably a different beast (but I never managed to see through Sphinx, so hard to tell for me). Anyway, I think just API docs is fine to start with (which goes into `doc/help`). People could always add their other, manual-like documentation into `doc/`. I'd be happy to help with this, if you need any. > Could you clarify the "interaction between source and docs" bit? > > On Wednesday, 11 June 2014 22:54:32 UTC+2, Mauro wrote: >> >> 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> 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 >>>>>>>>>>> >>>>>>>>>> >>>>>>> >>>>> >>> --
