Add at-doc and related code from Docile.

[MichaelHatherly]

This is some initial work to add @doc from Docile. I'm not sure if I've done the include and exports correctly -- it does work fine when calling using Base.Docstrings.

Only the module itself is exported from Base since I didn't feel adding additional exports was necessary.

I've retained the metadata section for each documented object (as per Docile), but I'm aware about the debate regarding whether to include metadata or not.

Hopefully this PR can further the discussion regarding package documentation.

TODO

• tests
• documentation

[MichaelHatherly]

Ref: #8514, MichaelHatherly/Docile.jl#40

[MikeInnes]

Rather than escaping the whole thing and then explicitly qualifying, it might be better just to escape specific parts.

[MikeInnes]

Ok, I'm not sure about this Doc{:md} construct, it's overcomplicating things. The raw doc system shouldn't need to know anything about parsing, just store some object and return it.

It's much more flexible if the string macro used controls any necessary lazy evaluation. This is already implemented for the md"" macro in Markdown.jl.

I also suspect that you're storing the parsed string (with default escapes, interpolation etc.) instead of the raw string, which will also cause issues (no one wants to have to double escape everything). Again, having the doc system trying to control parsing is unnecessary and brittle.

[MikeInnes]

It's worse than that, actually – having Docstrings in control of parsing actively blocks features of the Markdown parser. I need to be able to do things like adjusting image paths relative to the current file, registering the current module for lazy interpolation etc., which I cannot do as this PR stands. So yeah, simpler & more flexible without.

[MichaelHatherly]

That sounds reasonable to me. It's worked out well in it's current form for Docile so as to not need to import Markdown just to document things. Adding both features to Base does change that though, and your approach makes sense.
I don't have much time for the next few days to do anything major, and I really don't want to be the one to hold this up any longer. Feel free to add the necessary bits to the markdown PR if you'd like.

[MikeInnes]

Fair enough, thanks. I think the approach you used in Docile makes a lot of sense for the limitations of 0.3, but yeah, best to take a different tack for Base.

Anyway, I'll go ahead and add this tomorrow.

[MichaelHatherly]

Your new Markdown.jl readme page has sold me over. This will be really awesome once it's finished!