decide where documentation should live

[JeffBezanson]

Consensus seems to be that the current approach is not optimal. I'm leaning towards the idea of maintaining docs in the master repo under doc/ much like how test/ is there now. This will provide better development workflow and easier offline browsing.

An example approach from @nolta: http:https://readthedocs.org/docs/julia-test/en/latest/

[nolta]

Source for the example: https://github.com/JuliaLang/julia/tree/sphinx/doc

[pao]

Will we also establish policy for required documentation? It seems like a good idea.

[StefanKarpinski]

Will we also establish policy for required documentation? It seems like a good idea.

Can you elaborate on what you mean?

[pao]

What needs to be documented where before commit/pull. It's related to the base vs. extras vs. examples discussion.

[StefanKarpinski]

Gotcha. Yeah, we should do that and then try to actually stick to it ;-)

[nolta]

I've updated the sphinx branch, importing the whole stdlib and modifying help() to pull from doc/ instead of the website.

Before:

julia> help("open")
Downloading help data...
open(file_name[, read, write, create, truncate, append])
  Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file.

open(file_name[, mode])` - Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of `mode` correspond to those from `fopen(3)` or Perl `open`, and are equivalent to setting the following boolean groups

After:

julia> help("open")
Loading help data...
open(file_name[, read, write, create, truncate, append])

   Open a file in a mode specified by five boolean arguments. The
   default is to open files for reading only. Returns a stream for
   accessing the file.

open(file_name[, mode])

   Alternate syntax for open, where a string-based mode specifier is
   used instead of the five booleans. The values of 'mode' correspond
   to those from 'fopen(3)' or Perl 'open', and are equivalent to
   setting the following boolean groups:

   +------+-----------------------------------+
   | r    | read                              |
   +------+-----------------------------------+
   | r+   | read, write                       |
   +------+-----------------------------------+
   | w    | write, create, truncate           |
   +------+-----------------------------------+
   | w+   | read, write, create, truncate     |
   +------+-----------------------------------+
   | a    | write, create, append             |
   +------+-----------------------------------+
   | a+   | read, write, create, append       |
   +------+-----------------------------------+

[StefanKarpinski]

This looks really nice.

[timholy]

A huge step forward.

[timholy]

One question: there are obviously a lot of undocumented functions even within the standard library, some of which are powerful but probably not for "newbie" usage (e.g., gen_cartesian_map). Is the thought that we'd get these into documented form, too? If so, would this pose any challenges in organizing the documentation?

[JeffBezanson]

Yeah, we should just merge this as soon as we're ready. Nice work, Mike.

I guess we could have a section for power user functions. "Documented undocumented functions" :)

[pao]

I agree it would be best if no one has to start an "Undocumented Julia" blog, unlike a certain other technical computing language.

[nolta]

Thanks Stefan, Tim, & Jeff. I've tidied up the doc/ directory a bit, and i'm ready to merge when you are.

[timholy]

Mike, certainly there are no objections to merging from me.

[JeffBezanson]

Let's merge it!

[pao]

Whoo!