suggestion: links back to github

's Avatar


21 Oct, 2011 06:20 PM

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'.

  1. Support Staff 1 Posted by lsegal on 21 Oct, 2011 08:27 PM

    lsegal's Avatar

    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

  2. 2 Posted by Jonathan Rochki... on 21 Oct, 2011 08:47 PM

    Jonathan Rochkind's Avatar

    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. 3 Posted by Jonathan Rochki... on 21 Oct, 2011 08:49 PM

    Jonathan Rochkind's Avatar

    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?

  4. Support Staff 4 Posted by lsegal on 21 Oct, 2011 08:58 PM

    lsegal's Avatar
    1. 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).

    2. 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").

    3. 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.

  5. Support Staff 5 Posted by lsegal on 21 Oct, 2011 09:02 PM

    lsegal's Avatar

    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. 6 Posted by Jonathan Rochki... on 21 Oct, 2011 09:06 PM

    Jonathan Rochkind's Avatar

    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. 7 Posted by Jonathan Rochki... on 21 Oct, 2011 09:11 PM

    Jonathan Rochkind's Avatar

    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 or a version in 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. 8 Posted by Jonathan Rochki... on 21 Oct, 2011 09:24 PM

    Jonathan Rochkind's Avatar

    Okay, I see for the github stuff, the particular tag is avail in the

    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 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.

  9. Support Staff 9 Posted by lsegal on 21 Oct, 2011 09:30 PM

    lsegal's Avatar

    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. 10 Posted by Jonathan Rochki... on 21 Oct, 2011 10:10 PM

    Jonathan Rochkind's Avatar

    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 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 = "" + github_project +
                       "/blob/" + github_commit + "/" +
                       file +
                       "#L" + line;

             $(this).before(' <a href="' + url + '">[View on Github]</a>');

  11. 11 Posted by Jonathan Rochki... on 21 Oct, 2011 10:34 PM

    Jonathan Rochkind's Avatar

    sorry, email to ticketing system bad for code. if anyone wants to do anything with it, it's here:

  12. 12 Posted by Jonathan Rochki... on 21 Oct, 2011 10:35 PM

    Jonathan Rochkind's Avatar

    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.

  13. Support Staff 13 Posted by lsegal on 21 Oct, 2011 10:36 PM

    lsegal's Avatar

    I would suggest opening an issue on the 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.


  14. lsegal closed this discussion on 21 Oct, 2011 10:36 PM.

  15. Jonathan Rochkind re-opened this discussion on 21 Oct, 2011 10:39 PM

  16. 14 Posted by Jonathan Rochki... on 21 Oct, 2011 10:39 PM

    Jonathan Rochkind's Avatar

    Where do I find the tracker? I thought this WAS that,
    since it's where the link from "help" took me! on github?

  17. Support Staff 15 Posted by lsegal on 21 Oct, 2011 10:40 PM

    lsegal's Avatar

    Yes, sorry, I meant the page. Since this is code related, and not "the site is down!" related :)

  18. lsegal closed this discussion on 21 Oct, 2011 10:40 PM.

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts


? 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