WIP: Doc Transition

[MikeInnes]

This moves our 1503 docstrings from helpdb.jl into the new doc system. Docstrings are now stored in base/docs/helpdb.jl (soon to be scattered around base) and we have a hackish script which dumps those docstrings into the RST manual (at least until we move to markdown).

Caveats:

• Undocumented globals: ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"] – need to implement docs for variable bindings to fix this.
• helpdb didn't support multimethods well, so some functions and docstrings have duplicated entries.

On the whole though we should only have lost on the order of tens of docstrings, as opposed to thousands.

[MichaelHatherly]

unless you really hate blue

Could we just store them as plain text rather than MD objects?

[ViralBShah]

@MichaelHatherly Are you coming to JuliaCon? Would be great to sort this all out in person in case you are planning to be at MIT.

[MichaelHatherly]

@ViralBShah unfortunately I live many, many timezones away :( I'd have loved to be there though. I should be around for most of tomorrow so will be able to follow along.

[MikeInnes]

Could we just store them as plain text rather than MD objects?

Technically yes, although there's a risk of setting the precedent of plain text docs in Base being acceptable. This way it's obvious that the RST docs are a work in progress, which might be a good thing.

[MichaelHatherly]

risk of setting the precedent of plain text docs in Base being acceptable

Hopefully not if potential additions are reviewed, but I'm not particularly bothered about blue text for a little while – might make things move a bit faster :)

[hayd]

I had a branch which did the rst to md conversion (or pretty close) to something like https://gist.github.com/hayd/9cbd69e5e85693d1f6eb

I think it's this: hayd@246314b

Uses pycall/pypandoc to convert the rst docstrings to markdown, they need a little manual tweaking but pypandoc does a pretty good job.

[hayd]

This file is missing a header, as well as using 2 space indentation (rather than 4).

[tkelman]

ref JuliaIDE/Julia-LT#167

[hayd]

This appears to be missing the remainder of the line (after a ``... not sure if what's the pattern, but there's quite a few lines below which demonstrate similar - the diff should definitely be combed through).

Also this (function eye(A)) now appears three times as the same signature :s

[StefanKarpinski]

Superseded by #11906.

[Ismael-VC]

Undocumented globals: ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"] – need to implement docs for variable bindings to fix this.

One of the few things I liked about .NET when I was forced to use Visual Studio (and that now I miss in when I'm forced to use XCode 😁 ) was the ability to document global variables:

/// <summary>
/// Always use this
/// </summary>
List<string> my_list = List<string>();

Could we do something like this work?

"Returns the number of available CPU cores."
global CPU_CORES

function init_sysinfo()
    # set CPU core count
    global const CPU_CORES =
        haskey(ENV,"JULIA_CPU_CORES") ? parse(Int,ENV["JULIA_CPU_CORES"]) :
                                        Int(ccall(:jl_cpu_cores, Int32, ()))
    global const SC_CLK_TCK = ccall(:jl_SC_CLK_TCK, Clong, ())
    global const cpu_name = ccall(:jl_get_cpu_name, ByteString, ())
end

help?> CPU_CORES
...
Returns the number of available CPU cores.

[MikeInnes]

Yeah it's totally doable, just needs implementing.