Move docs for Base.Pkg into source file.

[MichaelHatherly]

A first pass at moving the docs for Pkg into the source file.

I've hit two bugs when trying this:

For Pkg.rm and Pkg.edit I've been getting

ErrorException("error in method definition: function Base.edit must be explicitly imported to be extended")))

when placing the docstrings above the methods, hence the use of function rm end.

I believe there's already an issue open for that, but can't find it at the moment (edit: probably #11798).

Second one:

help?> Pkg.dir
ERROR: KeyError: dir(path...) at pkg.jl:37 not found
 in getindex at dict.jl:695
 in doc at ./docs/Docs.jl:105

but I have confirmed that all the docs are in Base.Pkg.META. Not sure what the trouble is there.

I've just copy-pasted what was in helpdb.jl straight into the docstrings, so formatting could still use some work.

[MichaelHatherly]

Segfault on travis seems unrelated. Tests are passing locally.

[MichaelHatherly]

Formatting should match up with the previous rst source pretty well now. I've wrapped the docstrings at 92 chars and written the code syntax with double backticks, if that's not the style people would like I'm open to suggestions.

[MikeInnes]

This is great to see! About syntax, the docstrings are going to be parsed as Markdown and we (hopefully only temporarily) have an RST output backend, so yeah, we'll want to have single quotes for backticks.

I'll try and track down the errors you've found.

[MichaelHatherly]

we'll want to have single quotes for backticks

Fine by me. Switched out for single quotes, though the CommonMark Spec does allow for any number of consecutive backticks if I'm reading correctly.

[MichaelHatherly]

I'll try and track down the errors you've found.

@one-more-minute, it seems to be a dict rehashing problem and needs ObjectIdDictss instead:

$ git diff
diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
index ce76e31..6c8ffb5 100644
--- a/base/docs/Docs.jl
+++ b/base/docs/Docs.jl
@@ -75,11 +75,11 @@ end
 type FuncDoc
     main
     order::Vector{Method}
-    meta::Dict{Method, Any}
-    source::Dict{Method, Any}
+    meta::ObjectIdDict
+    source::ObjectIdDict
 end

-FuncDoc() = FuncDoc(nothing, [], Dict(), Dict())
+FuncDoc() = FuncDoc(nothing, [], ObjectIdDict(), ObjectIdDict())

 function doc!(f::Function, data)
     fd = get!(meta(), f, FuncDoc())
@@ -127,7 +127,7 @@ catdoc(xs...) = vcat(xs...)
 isdoc(x) = isexpr(x, :string, AbstractString) ||
     (isexpr(x, :macrocall) && endswith(string(x.args[1]), "_str"))

-dict_expr(d) = :(Dict($([:($(Expr(:quote, f)) => $d) for (f, d) in d]...)))
+dict_expr(d) = :(ObjectIdDict($([:($(Expr(:quote, f)) => $d) for (f, d) in d]...)))

 function field_meta (def)
     meta = Dict()
@@ -145,12 +145,12 @@ end

 type TypeDoc
     main
-    fields::Dict{Symbol, Any}
+    fields::ObjectIdDict
     order::Vector{Method}
-    meta::Dict{Method, Any}
+    meta::ObjectIdDict
 end

-TypeDoc() = TypeDoc(nothing, Dict(), [], Dict())
+TypeDoc() = TypeDoc(nothing, ObjectIdDict(), [], ObjectIdDict())

 function doc!(t::DataType, data, fields)
     td = get!(meta(), t, TypeDoc())

Fixes the KeyError:

help?> Pkg.dir
  dir() -> AbstractString
...

[MikeInnes]

Great! Can you PR that? I think the fields::Dict{Symbol, Any} part can safely stay as is.

[MichaelHatherly]

Will do, yeah I went a bit overboard with it, .fields can remain as is.

[MichaelHatherly]

With #11926 merged I'll close this and revisit later on once those problems have be solved.

[MikeInnes]

Yeah sorry about that, thanks a lot for the effort though.

[MichaelHatherly]

That's fine, it managed to shake out a bug so not a wasted effort.