Documentation

[Simon Byrne]

As the package ecosystem is rapidly expanding, I thought it could be useful to (re)start discussion on the documentation system. I don't know if there are any grand plans in the works, but I've been thinking about a couple of things (in roughly descending order of importance):

* Packages: a key problem is a standard for package documentation, and how best to incorporate package documentation into the help system. There are 4 options that I can think of:

1) keep the processed docs in the package repository (as is done in Julia itself at the moment), or some submodule.

2) add sphinx (or some other parser) as a dependency

3) write a parser in julia

4) maintain some hosted compilation of all package documentation: this would also allow one to search documentation of non-installed packages, and make it easier to have it all in the one place on readthedocs.

* How to handle multiple dispatch: a related problem is how to document methods that can have different behaviours for different types, particularly for packages that extend Base methods.

* There are some sets of methods that could easily be served by a common help page (e.g. all the A[tc]_mul_B[tc] methods).

* "See also" links to other relevant help items.

* Formatting: some judicious use of colour and spacing could make the terminal help much easier to read.

* Links to source: one of the great things about julia is that the source is easy to understand. It would make sense to have this readily accessible from the help.

* A quick introduction (and list of key differences) for people coming from R/Matlab/Python.

* Are there any novel/interesting things we should try (even in the long-term)? One very old suggestion (#52) was to automatically run all code in the examples (as in R). Another possible option is to have fully interactive code examples that could be run from within the help itself (as in Mathematica), perhaps via an ipython notebook linked to a separate julia process.

(I'm purposely avoiding the docstring debate, as that might best be left for a different thread)

-Simon

[Viral Shah]

The most important thing we need to do is to have package documentation. It would be a good start to have packages be able to register their documentation when installed, so that help() is aware of the package provided functions.

It seems that we can copy the help structure from base and also have readthedocs integration. There are a number of other questions that you raise, but it would be nice if the existing help() can be extended to include packages.

-viral

[Patrick O'Leary]

Viral, if you could create a repository to target in the JuliaLang organization, I can knock out https://github.com/JuliaLang/julia/issues/2379.