Rustdoc: add links to online source files if "url" attribute is present in crate

[bstrie]

Python does this for a few of its stdlib docs, as seen here: http://docs.python.org/py3k/library/socketserver.html

It would be pretty neat if Rustdoc could do this automatically by leveraging the metadata in the project's crate. To start, this would work easily for std:

#[link(name = "std",
vers = "0.2",
uuid = "122bed0b-c19b-4b82-b0b7-7ae8aead7297",
url = "https://github.com/mozilla/rust/tree/master/src/libstd")];

By taking the URL and appending the name of each source file you get valid pages:

https://github.com/mozilla/rust/tree/master/src/libstd/arena.rs
https://github.com/mozilla/rust/tree/master/src/libstd/bitv.rs

It's a bit more difficult for projects where the crate file is in the root directory:

#[link(name = "glfw",
vers = "0.1",
author = "alegalle",
uuid = "a1848f17-c60e-469d-8b12-8f1b45d2c31f",
url = "https://github.com/alegalle/rust_glfw")];

Note the difference between the naively appended URL and the true URL:

https://github.com/alegalle/rust_glfw/glfw.rs
https://github.com/alegalle/rust_glfw/blob/master/glfw.rs

Even if it means adding some Github-specific code, I think it would be worth it (especially since Github seems to be our "blessed" platform, and since rust_glfw registers the same URL with cargo-central, so Cargo must already be applying this transformation).

[bstrie]

Alternatively, we could establish a new convention where the URL attribute must actually point at the crate file, rather than just at the page where a link to the crate file exists.

[brson]

I'm not really sure what the purpose of the link url attribute is supposed to be, but we can probably come up with some heuristics to find a reasonable link based on a github url and the local directory structure. Possibly we can override it with #[doc(url = "")].

[catamorphism]

I don't feel very strongly about this, so I'm leaving it as an enhancement with no milestone. If someone wants to take this on, they should probably wait until #5679 is closed -- after that, maybe rustdoc could call into rustpkg somehow to do the inference that @brson suggested.

[emberian]

#8125

/cc @Seldaek

[emberian]

This is implemented a bit naively in rustdoc_ng, although it still needs a bunch of polish.

@catamorphism what rustpkg integration would this involve?

[huonw]

It might be better for rustdoc to actually package up the source itself, parallel to the actual docs, rather than link to some other online source:

• the source won't change underfoot and become out of sync with the docs, as naively linking to github.com/user/repo/tree/master/... would (and we don't have to work out how to handle different branches/revisions in each VCS)
• we aren't tied to a finite list of services and their link-to-a-specific-line-in-a-specific-file-in-a-specific-revision syntax
• we don't have to invent a syntax to specify how to link to the source (or make it reliable)
• best possible syntax highlighting via libsyntax (if this ever gets implemented)

This could even be inline in a page, so one can click-to-expand the function body (for example).

(Prompted by Ygg2 on HN.)

(cc @alexcrichton)

[chris-morgan]

+1 << N (for quite high values of N) for including the source, for the same reasons. My first inclination was "keep the size down by doing highlighting in JavaScript", but then I realised that we can do it better otherwise (JavaScript could still be used if desired which could lead to smaller files; the advisability of that can be considered later); we could even annotate it with cross-references to and fro, hither and yon, making it really useful.

Bear in mind, however, that it is possible that someone may not wish to reveal the source if they are writing a closed-source crate but still want docs. When this is implemented, the driver should have a flag added to disable it.

[huonw]

See also rustfind (source) for what can currently be done.

[Seldaek]

I for one would prefer links to github if that is available, because the source can't change if you link to the proper commit and not master, and because you get the full file at least, so you can browse around a bit as well.

That is, if you thought of embedding the entire source and a source browser and then linking to that, fine by me, but if it's just embedding the few lines relating to the function/struct/.. at hand, I think that's less powerful than github links.

[huonw]

What happens when someone is hosting their code on bitbucket, or on their personal website/company intranet (or in a completely different VCS)?

( My main suggestion is the entire source ala haddock docs → source (via the source link on the right).)

[Seldaek]

Yeah if you store everything as I said that's cool as well but it's a lot more work than just linking to github for now :)

[steveklabnik]

With Rails, we do both: http://api.rubyonrails.org/classes/ActionDispatch/Request.html (pick any method. there's an 'code' and a 'link to github' both.)

[alexcrichton]

I definitely agree that we should include the source in the page somehow, whether it's on github or just the source file itself. I'm actually quite in favor of including the source manually for the exact reason of version drift.

I doing something like rustfind would also be awesome, but it's probably not necessary right from the get-go. I'd like to add support for github source links, but right now I don't trust our versioning capabilities to be able to do that.

In the meantime, I will make it such that we at least render the source in some manner to the documentation directories and then we can always link into them.