RFC: towards scalable documentation

[timholy]

In the spirit of wrapping up Chaos Month, let me throw in some documentation chaos.

This bare-bones prototype addresses two issues:

1. Currently our helpdb contains one entry for each function name. But in Julia "sum" can do many different things depending on its inputs.
2. Previous discussions have gotten bogged down on the (de)merits of mixing documentation and code in the same files.

This aims to fix point1, and at least allow authors to make their own choices for point2.

Here's a demo file:

@doc double(x::FloatingPoint) "Multiply by two
  y = double(x)
y will be twice the value of x"
double(x::FloatingPoint) = 2x

@doc double(x::Int16) "When x is an Int16, this returns 3*x. Surprise!"
double(x::Int16) = 3x

And here's a sample session:

julia> helpdoc(double, 5.3)
Help for double:
Multiply by two
  y = double(x)
y will be twice the value of x

julia> helpdoc(double, int16(4))
Help for double:
When x is an Int16, this returns 3*x. Surprise!

julia> helpdoc(double, Int)
Help for double:

julia> helpdoc(double, Float32)
Help for double:
Multiply by two
  y = double(x)
y will be twice the value of x

julia> helpdoc(double)
Help for double:
Multiply by two
  y = double(x)
y will be twice the value of x
When x is an Int16, this returns 3*x. Surprise!

Some notes:

1. In solving point1, it seemed natural to use multiple dispatch in the help system. However, after thinking about it, I felt it might be best to use a modified version: if the user supplies help(func, args...) and args is of length n, then only worry about type intersection with the first n function arguments. This allows one to handle functions with optional arguments without additional @doc declarations.
2. As I indicated in comments in the code, my method for doing dispatch seems suboptimal. I could use some pointers from an expert.
3. For generating web-based documentation, we'd want some method for scanning .jl files to extract these documentation strings. Maybe the .rst files could be built from these?

[johnmyleswhite]

+1

[nolta]

1. Currently our helpdb contains one entry for each function name.

julia> help("read")
Base.read(stream, type)

   Read a value of the given type from a stream, in canonical binary
   representation.

Base.read(stream, type, dims)

   Read a series of values of the given type from a stream, in
   canonical binary representation. "dims" is either a tuple or a
   series of integer arguments specifying the size of "Array" to
   return.

[timholy]

@nolta, many thanks for the correction! You taught me something new.

However, even supposing one doesn't care about dispatching on the arguments as a mechanism to provide more specific help, am I right in guessing that this doesn't entirely obviate the need for some improvements in this area? For example, do we have a mechanism for packages to get their documentation loaded into helpdb? The approach here would also automatically handle that.

[tshort]

Cool idea, Tim. An @help macro might help in replace of helpdoc(), so you could do:

julia> @help double(pi)

The idea is you could stick @help in front of any normal call that you want help on, so it could find out the type signature for you.

[tshort]

If I'm interpreting your @doc macro right, you're creating various _doc_double methods. Another option is to use multiple dispatch for this like with a special DOC flag appropriately typed:

double(DOC, x::FloatingPoint) = "Multiply by two
  y = double(x)
y will be twice the value of x"

[tshort]

Another idea is to point to a file instead of using a string with one of these options:

@doc double(x::FloatingPoint) filename("double_fp.md")
@docfile double(x::FloatingPoint) "double_fp.md"
double(DOCFILE, x::FloatingPoint) = "double_fp.md"

You might want to be able to list multiple help resources:

@doc         double(x::FloatingPoint) "Multiply by two"
@docextended double(x::FloatingPoint) filename("double_fp.md")
@docvignette double(x::FloatingPoint) filename("double_fp.pdf")

[tshort]

See here for examples of the ideas above that relate to metadata associated with method definitions.:

https://github.com/tshort/Sims.jl/blob/master/doc/Possible-future-developments.md#one-option

[StefanKarpinski]

The @help idea is genius. We should do that.

[toivoh]

Very cool, Tim!
@tshort: It's probably not a good idea to use multiple dispatch to mix in the documentation with the function's regular methods. Might lead to a fair shower of ambiguity warnings...

[tshort]

Actually, this is one case that I don't think should add to the ambiguity messages because it's adding a specific type to the method signature rather than an abstract type.

It will clog up the display of methods, and for that reason, it may not be the best idea. Anyway, the idea of making @doc a macro is good in that it leaves open different options on how to actually store the metadata.

[timholy]

@tshort, thanks for the input! Glad to see some interest here, I was beginning to think this suggestion was sinking like a rock.

The only reason I generate those _doc_ functions is to extract the method signature---after I get the signature and put it into the dictionary, I effectively throw it away (or rather, I'd like to throw it away). I'm definitely asking for help (hint, @StefanKarpinski , @JeffBezanson , @vtjnash , etc) on how to get the method signature without actually having to build the function (i.e., methodsignature(ex::Expr)). I am sure I could write something, but it occurs to me that this must already be buried in either C or julia code somewhere, and it would be better to rely on something that already works. However, after having spent a couple of hours I couldn't find it. (I did learn a lot of cool stuff on the way, however!)

@help would just call helpdoc, so yes, that's very easy and it is a nice improvement in syntax. One thing to note about your second idea is that I'm doing a modified version of multiple dispatch here: if the user supplies only 2 arguments, it will print the help for any function that matches those first two arguments. Makes "optional" arguments a whole lot easier to deal with, which I think that's more appropriate for a help system. Hence, I don't want to rely on Julia's standard dispatch rules via double(DOC, x::FloatingPoint).

Finally, I too have wondered about "links" to other documentation. Matlab has a nice "see also" facility that makes exploration much, much easier. To your suggestions, we could add @seealso.

The key thing is, is there enough buy-in on this general framework for me to go forward with it? It's not a tiny project:

1. Make real versions of the prototypes I posted, and implement some of Tom's great suggestions for improvement.
2. Write a parser to generate .rst files so that we can use those doc strings for posting on the web or making PDF files.

I am also a little bit worried about whether documenting base/ in this way would have a perceptible impact on build or load times. Again, note that if you hate inline documentation, we could have a doc.jl file that just holds all the documentation for the standard library.

[timholy]

OK, so since I started writing that, lots more comments got posted. I'll take it as a "yes" that there's interest. Definitely hoping to hear about method signatures (and I'll keep looking myself).

[tshort]

You have buy-in from me. I like your general idea of @doc specs for attaching documentation to methods. The things I'm most interested in are what's needed for the package author, like:

• What format can I use for doc strings? I prefer Markdown over reStructuredText.
• If we point to files (in whatever format), where should these go?
• Are there any particular requirements like the following?

http://cran.r-project.org/doc/manuals/r-release/R-exts.html#Documenting-functions

• How is a module or a package to be documented?
• How can one hyperlink or cross-reference between help topics?

Multiline strings that can handle quotes would help, like:

"""
This is a "nice" comment.
"""

[tshort]

Another feature I'd like to see is easy viewing of package documentation on github. That could be done by a generate_docs(packagename) function or by having the default file format be one supported by github.

[nolta]

I'm skeptical about this project, just because i think you're going to end up rewriting sphinx, and that seems like a low priority.

Also, i'd be curious to hear why people prefer markdown over reStructuredText. They're basically the same, except rst is more powerful, w/ tables, blocks, block parameters, etc.

[johnmyleswhite]

Markdown is much cleaner than reStructuredText in my mind. If you're using rST, I feel like you might as well be using LaTeX.

[tshort]

I'm curious to hear more. Can sphinx use package documentation based on reStructuredText files I put in .julia/MyPackage/docs? Can sphinx understand multiple dispatch signatures? As a package writer, do I have to do anything other than write rst files?

I guess I like markdown because it's most familiar to me. Also, julia/doc/stdlib/base.rst looks bad when viewed on github.

[timholy]

I definitely want to hear skeptics. And Tom's most recent wish list is quite cautionary, frankly enough to make me doubt that I want to head down this path.

If we can do something like this within sphinx, I'm all ears. Here are real things I'm worried about in the current state of affairs, maybe you (@nolta) or others can suggest some solutions:

1. There do not seem to be any plans for getting package documentation into helpdb. Web documentation is nice, but by typing help(myfun) I can see something in 2s vs the half-minute (or more) it takes me to point a web browser at the right location.
2. Our current system indirectly encourages people to document just the "user-friendly" part of Julia. Other than the paper that the four founders are working on, we have no documentation whatsoever for the unfriendly parts. Personally, I'm more interested in the unfriendly parts :-). In my experience, having the option to put documentation into code tends to lead to more comprehensive documentation, especially of the sort that's of interest to reasonably-sophisticated developers. Of course we can type comments into the code, but currently there's no system for getting that information "out."

I think these are pretty big issues. Being able to do help-multiple-dispatch on arguments is really just a nice touch I threw in because I could. The real point was to begin addressing these two problems.

[nolta]

@johnmyleswhite: De gustibus non est disputandum, i guess.

@tshort: Extending the sphinx tooling to packages should be straightforward. And agreed that rst looks terrible on github, but that's a github bug, not an rst flaw.

@timholy: (1) I agree that we need an API for adding new entries to the helpdb. But calling the web docs "nice [to have]" seems a bit weird (to me at least). I think of the web docs as primary, and the online help as subordinate.

(2) I guess i'm the Bizarro Tim Holy: everything you think is bad, i think is good ;)

[timholy]

(1) Oh, don't get me wrong, I like the web docs too. I would be even happier with them if, for example, I could type help(myfunc) from the julia prompt and have it pop open a web browser to the right place. That might allow one to use all the sphinx goodness (links, etc) but not place the onus on the user to navigate.

(2) You're certainly not alone in not wanting code to be free of long documentation sections: I think you, Jeff, and Stefan agree on that, and I'd call that a quorum. But with many different people writing packages, some package authors would probably like to have more expansive documentation in the code (or at least, clearly linked to the code), but currently nothing in Julia supports that.

[timholy]

What about this:

@doc myfun(x::Type1, y::Type2) docfile("filename.html#section")

Then sphinx does all the markup; Julia, which knows about types, can easily find the right place.

[carlobaldassi]

As far as opinions go, I generally agree with @nolta.

More in detail, I'm concerned about the model for web docs, as it seems to me that there are two possible general models, a distributed and a centralized one. But since both have major drawbacks IMO, I'll propose a mixed model instead (which I have already sketched at some point on the dev list).

My idea is that, at least for official packages (i.e. the ones in METADATA) it should be possible to navigate to all of them, and get help from the repl for anything in any package, regardless if it's installed locally or not. Mostly, this requirement is for the sake of easily exploring functionality: for example, if I do apropos("gamma"), or if I search for "gamma" in the main Julia website, I think that the relevant topics from the Distributions package should come up. If I kind of know what a function in some package does, but I want to be sure and have ask for help quickly, I shouldn't need to install the package first. If I don't remember in which package a function was defined, I should be able to ask for help(func) and have that info printed.

Mike, you say it should be straightforward to extend sphinx tooling to packages. Maybe I'm don't know enough about it, but it seems to me that in a distributed approach one would need to have a doc/ directory for each package, modelled after Julia's one, have an independent website for each package, and link all documentations together via intersphinx. But from what I understand this would still require maintenance of all cross links (so the model wouldn't be fully distributed after all), and wouldn't allow for global searches and won't generally address all other issues outlined above.

On the other hand, having all docs in the Julia website would clearly be a pain to manage and basically just wrong.

So, one admittedly ugly bit simple and maybe viable idea I had is that each package should hold its own rst files in a more or less standard format, and those could be automatically fetched and kept in the julia repo by some make fetch_package_docs command, just like it happens now for make helpdb.jl; all the extra work would be just a matter of filling some template. This could also be used to keep versioned pages, i.e. help pages for different versions of each package (which is one more issue to consider when designing the docs system, given how the package manager works). With all the information maintained in distributed form but fetched in a central place, the local help() & friends functions could be kept as they are now, or improved upon to do dispatch, or whatever. (Also, if we want to support writing docs alongside the code, that could be fetched as well.)

Am I wrong about the distributed approach? Can anyone think of a better solution?

[johnmyleswhite]

I agree with @carlobaldassi that we ultimately want a mixed approach so that I can search through the documentation for uninstalled packages.

I am quite ignorant about the details of Sphinx, but one point I don't recall seeing raised in our documentation discussions is how we are going to insure that the documentation for each package uses a consistent format. The examples I've seen are one-liners, but we're ultimately going to want to require that every package document every exported function in a format that clearly separates things like:

• The function name
• The type signature of the arguments
• The type signature of the return value
• A one-liner description
• An extended description
• An example of use

[timholy]

@carlobaldassi , your suggestion is basically what I meant by @doc myfun(x::Type1, y::Type2) docfile("filename.html#section"). The idea is to build a link between Julia's type system and local documentation. Certainly we should generate those references automatically, rather than needing to type them in. Personally I favor the idea that:

1. each package keeps a doc/ directory
2. the package manager always builds the html and helpdb.jl documentation whenever the package is installed/updated
3. we have a good way of linking between functions and package documentation, both for text-based help (especially useful if people are logged in remotely to a machine without graphical access) and html help.

Just to illustrate the importance of this point further, for the specific @nolta case where we want to make the pretty html documentation primary: suppose I'm coding away in Matlab. I need to use the find_first_stimulus_delivery function, but I can't remember the order of the arguments. After typing the name, I hit F1, and up pops the documentation. Time to reach documentation: 2s

Coding in Julia: I'm programming away, I need to use the find_first_stimulus_delivery function, I type find_first_stimulus_delivery on the command line, I discover it's in some file called "stimulus.jl". Then I drop to the Unix prompt, type "locate stimulus.jl", and discover it's in "~/.julia/TimHolysElectrophysiologyPrograms". I then "cd" to the doc/ subdirectory of this directory, and type "chromium-browser index.html". I then search through this file until I find the function I want. Time to reach documentation: about 30s.

Especially if we want to make the web documentation primary, it has to be a lot easier than it is now.

[timholy]

@johnmyleswhite, +1 for all the items on your list. As someone who has a lab full of scientist/programmers who don't have the sophistication of your typical Julia developer, I have evolved to become a believer in the value of code examples as a component of good documentation.

[timholy]

@carlobaldassi , I started at the end of your comment. The beginning part, about not-yet-installed packages, is compelling too. A bit scary, though; I wonder if it could become a needle-in-a-haystack problem, especially if we get to 10,000 packages some day.

[JeffreySarnoff]

+1 for promulgation of clarifying examples
+1 for parceling pithily parallel paragraphs

[staticfloat]

For what it's worth, I also think @timholy's idea of putting documentation in standalone files, but annotating Julia code with the location of the corresponding documentation in those standalone files is a good one. This strikes a balance between the "documentation should live where the code lives" and the "documentation should be gathered in one place so it doesn't clog up the code" camps, and even gives us some nice computational tools to process this data. (Interactive code will know where to go to get documentation for a function object, doc tools don't have to speak Julia to parse documentation and turn it into something else, like HTML)

As far as what the documentation is actually written in, I think that's less of an issue. ReST, Markdown, LaTeX, .docx files using the Equation editor, it doesn't matter too much. All I would say is we should achieve an ease of use similar to ipython's Markdown and MathJax (a javascript LaTeX renderer) mashup; it makes mixing prose and math a breeze.

[carlobaldassi]

@johnmyleswhite: Maybe I'm an optimist, but I think a reasonable approach towards insuring some standard documentation format would be through a mix of clear guidelines, opening issues/pull requests in the packages repos, having a package skeleton to start from for new packages. Maybe in the future a "validation" script to spot the most obvious problems might be conceivable. So I don't think of it as an urgent problem at the moment. I agree on your points about annotating all parts of a function and I think Sphinx supports that, but it probably needs some Julia-specific code and definitions in the parser, since at the moment it is tailored on Python. Plus, it's not completely obvious how to organize the presentation of all the required information in the presence of multiple dispatch (and the ability of packages to leverage that) without making it extremely heavy. This is not a lightweight project. Examples would probably be less of a problem though.

@timholy: I'm confused. To be honest, I don't quite understand your example about how to look for info about the arguments of a function in Julia: what you describe (delving into the file system hierarchy etc.) is only true for undocumented functions (which shouldn't exist at all for anything in Base and any package version beyond v0), otherwise help("find_first_stimulus_delivery") would indeed tell you what the arguments are, no matter if the documentation is provided via rst files or it's attached to the code in formatted comments, provided it has been parsed into helpdb.

So, about your points: 1) I agree that each package should have its own doc/ directory; 2) I'm concerned about the fully distributed approach of having each package build its own helpdb and html, as I wrote; 3) I like the idea of storing an explicit link between any exported functions and its html documentation for the sake of being able to fire up the relevant portion of the html help from the command line (but see below for more on that).

About the comparison with Matlab: I know how good it can be when you hit F1 and an html-like help window pops-up, complete with links etc. It's even better in Mathematica. But in both those cases, this is possible because 1) you're working within a graphical IDE (try matlab -nodisplay -nosplash -nodesktop -nojvm and then try using F1 or issuing help somefunction), and 2) all the documentation is installed locally. Moreover (and more importantly) the model there is not to have an extremely slim Base module with all kinds of functionality provided via packages (installed locally and on a per-user or even per-project base), so I think it's very important for Julia that there is a way to know what you need for performing a task.

So: having something like F1-keypress work is probably only feasible when working in some kind of graphical environment (e.g. the web repl?); opening a browser when you issue help(something) in a terminal is surely doable if we have a link from functions to documentation as you suggested, but I'd rather have it be optional (e.g. by a separate webhelp function or something), since the text version is surely faster and only relies on helpdb.jl being installed.

As per the needle-in-a-haystack potential problem, I think it's basically unavoidable (think of the tons of stuff which come up in any search in Matlab's help or in the Python documentation website); the only way out is probably having a good search mechanism, and maybe (?) annotating the docs by using some tags to help filtering results.

[timholy]

@carlobaldassi

I don't quite understand your example about how to look for info about the arguments of a function in Julia: what you describe (delving into the file system hierarchy etc.) is only true for undocumented functions (which shouldn't exist at all for anything in Base and any package version beyond v0), otherwise help("find_first_stimulus_delivery") would indeed tell you what the arguments are, no matter if the documentation is provided via rst files or it's attached to the code in formatted comments, provided it has been parsed into helpdb.

Unless I'm mistaken, currently there is no mechanism for parsing documentation that lives in a package into helpdb. I don't think it will scale to have every package's documentation in JuliaLang/julia/doc/stdlib. Note that every file in doc/stdlib predates packages. @nolta has some very nice documentation in a doc/ directory of Winston.jl, but in my brief survey that's a bit unusual.

I also am in favor of making plain-text documentation "primary" via help and having a separate webhelp (I'd prefer helpw since it will be more easily discovered by tab-completion). I was just illustrating the challenges inherent in Mike's suggestion that web docs should be primary. For particular cases like graphics, the pretty-printing of web-based help will be almost essential for "detailed" help (i.e., show people what the result looks like), but something quick like an explanation of the arguments only needs text.

[toivoh]

@carlobaldassi: Thanks, that was the kind of thing I was thinking about. Is it documented somewhere, so that others can find it too?

[timholy]

@carlobaldassi and @StefanKarpinski, what about having an optional "keywords" file in JuliaLang/METADATA.jl? That could be the basis for searching for not-yet-installed documentation, without "polluting" the detailed database of function names and descriptions. For example, when one types help(find) one will only see help for find functions that are installed; typing apropos("collections") searches all possible packages.

We'd also need to start tagging help by module, so that people know what using commands they need to execute in order to have any given function available.

Bottom line: having packages is divine, but I think we need to put some effort into their documentation.

[carlobaldassi]

@toivoh: I don't think it's documented anywhere. But it seems this is not the best time for documenting the documentation ;)

@timholy: my point was that missing documentation should simply not happen. It is so right now for packages because nobody's sure on how to proceed (at least that's true for me), but in my view, once there's an agreement, no package should be undocumented except while in "wild development" mode (v0). I'd go as far as refusing to acknowledge inclusion in the official METADATA if a package claims to be at version 1 and lacks a complete API documentation (but then maybe it's just me). So I assume that help(something) will at the very least print some quick reference, no matter the details of the documentation system.

The concern about scalability is a relevant one. I take you're concerned about issuing help(find) and see 1000 function definitions. I think that dispatching on the arguments could indeed provide a great way to filter results. Another way could be specifying the module, e.g. help("Base.find"), but this won't help much in this case. So what about simply having some optional arguments to help and related functions (or the macros which will substitute them) which allow to decide if the results which come up should include all installed packages or not, and maybe do some more advanced filtering?

About keywords in METADATA: I think associating keywords with packages would be helpful, and having summaries of what each package has to offer would be even better, but if that's an alternative "mixed" model, in which summary info is centralized and detailed info is distributed, I'm not convinced: regardless what you see as "primary", I think it's at least reasonable to say that the documentation of any package should be available in html format, and should be reachable from the Julia website. This means that either all pages are built and uploaded online independently, and the links between them are managed manually (I don't think this is doable) or the pages are fetched in the central repo, built all together and uploaded on a single site (I'd love to have better alternatives, but this is the only viable way I can think of). But if we go for the second option, then we might as well fetch all there is to fetch, so there's no need to have METADATA as another "information hub".

One thing which would still be very necessary, even in the approach I'm advocating, is the possibility for installed packages to integrate and supersede the centralized documentation (in particular if the centralized helpdb is installed system-wide and it's not writeable, while the packages are installed in the user's directory and can get updated).

[tshort]

Today, I tinkered around with a decentralized approach for package help. See here for a package I set up as a testbed:

https://github.com/tshort/HelpTestbed.jl

The main idea is that everything is decentralized. Nothing needs to be generated when you add a package. Help commands and browser-based help both go looking for help. From the REPL, you could ask for help in several ways:

@help mydataframe["col1"]   # figures out the function name and package based on the function call
@help DataFrames.ref        # lookup by module and keyword name (must be loaded)
@help DataFrames ref        # lookup by package and keyword name
help(DataFrames.ref)        # same but from a function definition 
help("DataFrames", "ref")   # string-based lookups

All of the above end up calling the same function: help("DataFrames", "ref"). The main mapping is by package and then keyword. Keywords would normally be defined for every exported function and type.

For browser-based help, we could feed web pages to the browser from the Julia webserver. Using
live feeds from our own webserver, we could provide a search bar, a common header, and handle cross referencing between packages.

[timholy]

Tom, I won't have time to look at this today, but I'm glad to see your efforts here! It looks promising.

[tshort]

Thanks Tim. I made a bit more progress. I have a working @help macro, so you can do things like:

julia> load("HelpTestbed"); using Help

julia> @help sin
Loading help data...
Base.sin(x)

   Compute sine of "x"

julia> @help sin(1)
sin(Real,) at math.jl:86

Base.sin(x)

   Compute sine of "x"

julia> m = Modelica.MyType(1)
MyType(1)

julia> @help sin(m)
sin(MyType,) at /home/tshort/.julia/HelpTestbed/src/HelpTestbed.jl:166

Package `HelpTestbed`,  sin

Miscellaneous trig functions

# Basic trig operations

sin(x::MyType)
cos(x::MyType)

That's it...

[tshort]

The RDatasets package now has documentation along with a _JL_INDEX_ file that can be used with the HelpTestbed package for searching (apropos) and @help. It's another large set of documentation useful for experimentation.

[lgautier]

@carlobaldassi : I am chiming in a little late, but one comment regarding enforcing documentation coming from experience with R. I'd favour making it easy to write documentation over enforcement, and unobtrusive warnings in case of missing documentation would seem to me a better stand to take.
In particular, my understand is that the METADATA can be customized in order to serve other packages than the official one. I fully agree that the official METADATA will want to impose acceptance rules, but other repositories should be left with their own policies.

[vtjnash]

bump. it appears this would address several other open issues. what are the remaining concerns with this right now?

[timholy]

This seems to be a big topic, not the incremental step I was hoping for when I first ventured the topic. There seem to be several unresolved design issues. Here's my attempt to summarize them; I think there are really two main issues.

First: how much documentation should be available, and when? There seem to be at least three choices:

1. All available packages' documentation is available via help at all times
2. All installed packages' documentation is available via help at all times
3. All packages that you're currently using have their documentation available

My original pull request essentially does the third. IIUC, @carlobaldassi is suggesting we do the first. I now agree that the third is probably not adequate, but I wonder whether the second has some advantages. It seems that this issue needs to be resolved before any further steps can be taken.

Second: how should the help should be represented? @nolta correctly points out that abandoning sphinx has disadvantages. However, integrating dispatch into the help system (the original "gimmick" in this pull request) also seems to have struck a chord. I have a suspicion that it might be possible to do this via sphinx (sphinx can clearly be used to generate a julia-parseable file, as witnessed by helpdb.jl), but currently I'm too ignorant about (& insufficiently educated about the merits of) sphinx to dream of tackling that in the time before the ubuntu deadline.

@tshort and @johnmyleswhite have both pointed out that there are several types of help (brief, detailed, examples, etc.) you might want to get; help alone is probably not enough. This is a factor to consider in the representation issue. Again, since sphinx can generate julia parseable files this is presumably achievable.

[tshort]

For 0.1, there's really only time to ship with what we have. It covers Base pretty well.

Longer term, we need to have a way to integrate documentation from packages into online help. Sphinx could be adapted to this, or we could support multiple systems. In some experiments that I did, a system doesn't need to be "pre-compiled"--it can search through each package directory fast enough.

I think we also need HTML help. That's the best looking and most interactive way for users to dig into documentation. Right now, we could have help(cmd) or @help cmd generate HTML and launch a browser. I don't think there's a way to have the browser talk back to the Julia session controlled by the REPL. With one of the HTTP server options, I could have the browser talking to a separate Julia session, but not the same one. Having this communication is important, so the user can browse loaded packages and get whos like information that's in sync with what's in the REPL.

[ViralBShah]

@timholy I think it would be great if we could at this time achieve the third point you refer to - all installed packages have their documentation available through help.

We do need more comprehensive documentation within Base, and support all kinds of stuff in the help for any given function: calling, brief description, detailed help, examples, illustrations, citations, etc. This is perhaps a longer term effort.

For now, as a baby step, if packages can adopt the documentation infrastructure that is used in Base, and help and something like apropos can look through these, it would be fantastic. Should we try to achieve that in this pull request?

[timholy]

Given the relative lack of consensus, baby steps seem good, and I agree that the need to document and search packages is growing. (Jeff's brilliant and incredibly useful "add the parameter names to method dumps" patch notwithstanding.)

But sadly I'm short on time right now and need to use what Julia-time I have for other coding priorities, so if we're going to do something on this issue I'm afraid someone else will have to lead this charge.

[shabbychef]

Can anyone speculate on the odds that a 'Joxygen'-like module will be developed in the not too distant future to convert Doxygen style in-line documentation to whatever format becomes the Julia standard? I would like to start writing code, but want to document as I go.

[tshort]

I second Tim's statement. Baby steps seem good.

On Fri, Apr 5, 2013 at 1:26 PM, Steven Pav [email protected] wrote:

Can anyone speculate on the odds that a 'Joxygen'-like module will be
developed in the not too distant future to convert Doxygen style in-line
documentation to whatever format becomes the Julia standard? I would like
to start writing code, but want to document as I go.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/1619#issuecomment-15969227
.

[StefanKarpinski]

Jeff's brilliant and incredibly useful "add the parameter names to method dumps" patch notwithstanding.

If I recall correctly, credit is actually due to @vtjnash.

[JeffBezanson]

Nope, it was me, but vtjnash probably fixed and improved it. And now that
we have optional and named arguments, it is useless again :P
On Apr 5, 2013 3:22 PM, "Stefan Karpinski" [email protected] wrote:

Jeff's brilliant and incredibly useful "add the parameter names to method
dumps" patch notwithstanding.

If I recall correctly, credit is actually due to @vtjnashhttps://github.com/vtjnash
.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/1619#issuecomment-15975399
.

[timholy]

Kudos to @vtjnash too!

And now that we have optional and named arguments, it is useless again :P

Useless is probably too strong, but yes, I see what you mean! But in that sense much of the existing documentation could become obsolete.

[vtjnash]

I don't think I can take any credit for it. All I recall doing was opening a bug report for Jeff shortly afterwards for some failure case of it.

[Keno]

Is this pull request still relevant?

[stevengj]

See also #762