suggestion: links back to github
Odds are you've thought of this already, but just in case you haven't:
For help autogenerated from a github fetch, it would be awesome to have link back to the original sourcefile on the github web html ui (even exact line number using anchor?), displayed with every method next to 'view source'.
Comments are currently closed for this discussion. You can start a new one.
Keyboard shortcuts
Generic
| ? | Show this help |
|---|---|
| ESC | Blurs the current field |
Comment Form
| r | Focus the comment reply box |
|---|---|
| ^ + ↩ | Submit the comment |
You can use Command ⌘ instead of Control ^ on Mac
Support Staff 1 Posted by lsegal on 21 Oct, 2011 08:27 PM
It would actually be possible to build with js and add in the templates like we do in the yard server for permalinks. Would you want to take a stab at it? :) The code is at https://github.com/lsegal/rubydoc.info
2 Posted by Jonathan Rochki... on 21 Oct, 2011 08:47 PM
Do you mean it would only be added in after page load with JS? It
seems a lot preferable to have the links there in initial page
generation even without JS, no?
Either way.... I dunno if I can find the time to do it or not, but maybe!
3 Posted by Jonathan Rochki... on 21 Oct, 2011 08:49 PM
You'd need access to the fact that the doc was generated from github,
and what the github project URL was though... is this avail in JS?
Also access to the source file and line number from the source file
that a particular method came from --- you are displaying the
sourcefile/line number now (very useful in general, thanks!), but
screen-scraping it out of the HTML with JS doesn't quite seem like the
right way to do this. No?
Support Staff 4 Posted by lsegal on 21 Oct, 2011 08:58 PM
Yes, we could generate it in HTML and not use JS, but being a static asset, we could update the site and add support for github links on all pages without having to regenerate any cached html files (of which we have a lot). So that's a big plus for playing with new features. Also, I suggested it because my guess is doing it with JS would be easier for you than figuring out the templating system-- although it's not impossible to learn, it's nothing like the Rails you may be used to (I'm assuming you do Rails here).
As for JS, it wouldn't really be "screen scraping", it would be a simply DOM operation, which I think is completely reasonable. But yes, you would grab the source blob. The file/line can be parsed out of the first line of the source. The css selector would be
$(".source_code .info.file").As for telling if it's generated from github, you can just match for "/github" in
window.location.pathname(or equivalent), since all github hosted projects are under that path.That's how I would do it using JS.
Support Staff 5 Posted by lsegal on 21 Oct, 2011 09:02 PM
BTW, my suggestion would be to put a link labeled "github" (or "on github") next to the View Source link, not on each individual line in the annotated view. This would be injected along with the rest of the JS, assuming we use JS.
Alternatively, we could just rewrite the view source to link to github-- then we could not generate source locally at all. That would cut down on the time we spend generating html pages and make page load just a bit faster... interesting possibility there.
6 Posted by Jonathan Rochki... on 21 Oct, 2011 09:06 PM
Okay, thanks for the hints. If you think this works best as JS, I can
try doing it that way -- I'll see if I have time to do this myself
next week; what's the right way for me to try testing my code?
Hopefully not run a clone of your entire server locally, so I can test
the window.location stuff myself!
Hmm, just do it with the JS debugger of my choice manually, and figure
it'll work if it's in the JS file you reference, and then send you a
pull request for that?
I do do Rails, I also do other non-Rails ruby and am not too scared of
learning about your templating system, but you're probably right that
doing it in JS it's a lot likely that i myself will find time to try
adding this. If you'd like it in JS and are willing to add it if I do
it in JS, I'll try to do it!
7 Posted by Jonathan Rochki... on 21 Oct, 2011 09:11 PM
Yes, I agree, not on each individual line.
I think it's probably useful to have the current 'view source' as well
as the link to github. It's, I guess, just going to link to 'master'
in github. If for whatever reason master in github is no longer the
same as what the doc was generated from, or if github is down (okay,
unlikely)... or for that matter, if you do just want a quick look at
the source, you'd rather have it in a very quick in-page-shown-by-
javascript, then a link to another page. I noticed that one set of
rails api/rdoc documentation now has a "link to github" on it (I
forget which one/where at the moment), but it had both the typical in-
page-js-shown view source, as well as the link to github. I think both
are probably useful to have.
I'd personally discourage you from removing the inline js-shown source
altogether, even if a link to github is added, I think it's useful to
have both. Especially the issue with possibly multiple versions of a
library in documentation (ie the multiple versions of rails on
rubdoc.info) or a version in rubydoc.info that matches a release
instead of 'master' -- my initial stab at this definitely isn't going
to be smart enough to link to the _right_ snapshot for the version of
documentation (not sure if that's even possible from a pure-JS
implementation, is the particular tag or sha hash avail in any way to
the JS? If it is, I'll try to make my stab at it take account!).
8 Posted by Jonathan Rochki... on 21 Oct, 2011 09:24 PM
Okay, I see for the github stuff, the particular tag is avail in the
URL.
But okay, here's the trick I guess there's no way around -- I see that
you are now auto-generating docs (or at least hte stub that's
generated when accessed) for all gems? That's awesome.
But for instance, a project I work on --- now I see we've got docs on
rdoc.info in the 'github' area due to our github post commit hooks --
and we've ALSO got docs in the 'gems' area (in fact, for each
version!)... this technique we're talking about will sadly only work
on documentation in the 'github' area, not the 'gems' area, because
there's no way to know that a gem was controlled in github.
Any way around this you can think of? I think these days most people
(including myself) are going to end up looking at docs in the 'gems'
area, making this feature less useful if it only applies to the
'github' area.
Support Staff 9 Posted by lsegal on 21 Oct, 2011 09:30 PM
Right, this would be a github specific thing.
Honestly? I don't know of any good way to map gems to github. Frankly, there isn't really a reliable way-- the best would be to try to find a tag matching the version, but these aren't always available. It would be wrong, in this case, to map a gem's source to master-- that would most definitely yield invalid source lines after a very short period of time. So yes, this would only work on the github code, unfortunately.
As for testing-- you can clone the repo and run your own local server, this is the best way. It's not as tough to test as you think-- the URL paths should be the same locally as on the server (/github). Remember, you'd be matching against
window.location.pathname, not the host/port.10 Posted by Jonathan Rochki... on 21 Oct, 2011 10:10 PM
Okay, here's some JS that works. (There's probably a more cleverly
idiomatic functional jquery way to do this, but this seems good enough
to me). It even seems to work on "attributes" not just methods, which
I wasn't expecting, but your DOM is consistent in nice ways so it
surprised me and added links to github that worked there too, woo.
I haven't actually cloned the repo or gotten my own server started, I
just did this JS greasemonkey-style. I have to admit my enthusiasm is
sapped realizing that this will only apply to the 'github' section,
when most of my use of rubydoc.info is actually the 'gem' section, and
I assume most other users the same. Too bad the rubygems
infrastructure isn't quite good enough to support this for 'gems'
section, I think (and if it was, it would require some actual back-end
changes to your code, not just JS, probably).
So do with it what you will! It is pretty cool, if nothing else maybe
i'll make a javascript bookmarklet for myself that applies it, for the
minority of times I'm looking at 'github' area rather than 'gems'
area, alas! Thanks for your hints and feedback.
****
if (match = window.location.pathname.match(/^\/github\/([^\/]+\/[^/]+)
\/([^/]+)/)) {
var github_project = match[1];
var github_commit = match[2];
$(".source_code").each( function() {
if (match = $(this).find(".info.file").text().match(/^# File
'([^']+)', line (\d+)/)) {
var file = match[1];
var line = match[2];
var url = "https://github.com/" + github_project +
"/blob/" + github_commit + "/" +
file +
"#L" + line;
$(this).before(' <a href="' + url + '">[View on Github]</a>');
}
});
}
11 Posted by Jonathan Rochki... on 21 Oct, 2011 10:34 PM
sorry, email to ticketing system bad for code. if anyone wants to do anything with it, it's here: https://gist.github.com/1305162
12 Posted by Jonathan Rochki... on 21 Oct, 2011 10:35 PM
and crap, the place I insert it into the DOM messes up the current view source/hide source links. Ah well, it's a start if anyone wants to run with it.
Support Staff 13 Posted by lsegal on 21 Oct, 2011 10:36 PM
I would suggest opening an issue on the rubydoc.info tracker and linking your gist there as well. And thanks, we might just be able to get this installed!
I'll close this issue here, we can track it on github if you open it there.
Loren
lsegal closed this discussion on 21 Oct, 2011 10:36 PM.
Jonathan Rochkind re-opened this discussion on 21 Oct, 2011 10:39 PM
14 Posted by Jonathan Rochki... on 21 Oct, 2011 10:39 PM
Where do I find the rubydoc.info tracker? I thought this WAS that,
since it's where the link from rubydoc.info "help" took me!
rubydoc.info on github?
Support Staff 15 Posted by lsegal on 21 Oct, 2011 10:40 PM
Yes, sorry, I meant the http://github.com/lsegal/rubydoc.info/issues page. Since this is code related, and not "the site is down!" related :)
lsegal closed this discussion on 21 Oct, 2011 10:40 PM.