tag:rubydoc.tenderapp.com,2010-12-26:/discussions/suggestions/4-suggestion-links-back-to-githubRubydoc.info: Discussion 2011-10-21T22:40:59Ztag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T20:27:48Z2011-10-21T20:27:48Zsuggestion: links back to github<div><p>It would actually be possible to build with js and add in the
templates like we do in the yard server <a href=
"https://github.com/lsegal/yard/blob/master/lib/yard/server/templates/default/fulldoc/html/js/live.js">
for permalinks</a>. Would you want to take a stab at it? :) The
code is at <a href=
"https://github.com/lsegal/rubydoc.info">https://github.com/lsegal/rubydoc.info</a></p></div>lsegaltag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T20:47:41Z2011-10-21T20:47:41Zsuggestion: links back to github<div><p>Do you mean it would only be added in after page load with JS?
It<br>
seems a lot preferable to have the links there in initial page<br>
generation even without JS, no?</p>
<p>Either way.... I dunno if I can find the time to do it or not,
but maybe!</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T20:49:12Z2011-10-21T20:49:12Zsuggestion: links back to github<div><p>You'd need access to the fact that the doc was generated from
github,<br>
and what the github project URL was though... is this avail in
JS?<br>
Also access to the source file and line number from the source
file<br>
that a particular method came from --- you are displaying the<br>
sourcefile/line number now (very useful in general, thanks!),
but<br>
screen-scraping it out of the HTML with JS doesn't quite seem like
the<br>
right way to do this. No?</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T20:58:16Z2011-10-21T20:59:19Zsuggestion: links back to github<div><ol>
<li>
<p>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).</p>
</li>
<li>
<p>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
<code>$(".source_code .info.file")</code>.</p>
</li>
<li>
<p>As for telling if it's generated from github, you can just match
for "/github" in <code>window.location.pathname</code> (or
equivalent), since all github hosted projects are under that
path.</p>
</li>
</ol>
<p>That's how I would do it using JS.</p></div>lsegaltag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T21:02:47Z2011-10-21T21:03:30Zsuggestion: links back to github<div><p>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.</p>
<p>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.</p></div>lsegaltag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T21:06:14Z2011-10-21T21:06:14Zsuggestion: links back to github<div><p>Okay, thanks for the hints. If you think this works best as JS,
I can<br>
try doing it that way -- I'll see if I have time to do this
myself<br>
next week; what's the right way for me to try testing my code?<br>
Hopefully not run a clone of your entire server locally, so I can
test<br>
the window.location stuff myself!</p>
<p>Hmm, just do it with the JS debugger of my choice manually, and
figure<br>
it'll work if it's in the JS file you reference, and then send you
a<br>
pull request for that?</p>
<p>I do do Rails, I also do other non-Rails ruby and am not too
scared of<br>
learning about your templating system, but you're probably right
that<br>
doing it in JS it's a lot likely that i myself will find time to
try<br>
adding this. If you'd like it in JS and are willing to add it if I
do<br>
it in JS, I'll try to do it!</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T21:11:26Z2011-10-21T21:11:26Zsuggestion: links back to github<div><p>Yes, I agree, not on each individual line.</p>
<p>I think it's probably useful to have the current 'view source'
as well<br>
as the link to github. It's, I guess, just going to link to
'master'<br>
in github. If for whatever reason master in github is no longer
the<br>
same as what the doc was generated from, or if github is down
(okay,<br>
unlikely)... or for that matter, if you do just want a quick look
at<br>
the source, you'd rather have it in a very quick
in-page-shown-by-<br>
javascript, then a link to another page. I noticed that one set
of<br>
rails api/rdoc documentation now has a "link to github" on it
(I<br>
forget which one/where at the moment), but it had both the typical
in-<br>
page-js-shown view source, as well as the link to github. I think
both<br>
are probably useful to have.</p>
<p>I'd personally discourage you from removing the inline js-shown
source<br>
altogether, even if a link to github is added, I think it's useful
to<br>
have both. Especially the issue with possibly multiple versions of
a<br>
library in documentation (ie the multiple versions of rails on<br>
rubdoc.info) or a version in rubydoc.info that matches a
release<br>
instead of 'master' -- my initial stab at this definitely isn't
going<br>
to be smart enough to link to the <em>right</em> snapshot for the
version of<br>
documentation (not sure if that's even possible from a pure-JS<br>
implementation, is the particular tag or sha hash avail in any way
to<br>
the JS? If it is, I'll try to make my stab at it take
account!).</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T21:24:04Z2011-10-21T21:24:04Zsuggestion: links back to github<div><p>Okay, I see for the github stuff, the particular tag is avail in
the<br>
URL.</p>
<p>But okay, here's the trick I guess there's no way around -- I
see that<br>
you are now auto-generating docs (or at least hte stub that's<br>
generated when accessed) for all gems? That's awesome.</p>
<p>But for instance, a project I work on --- now I see we've got
docs on<br>
rdoc.info in the 'github' area due to our github post commit hooks
--<br>
and we've ALSO got docs in the 'gems' area (in fact, for each<br>
version!)... this technique we're talking about will sadly only
work<br>
on documentation in the 'github' area, not the 'gems' area,
because<br>
there's no way to know that a gem was controlled in github.</p>
<p>Any way around this you can think of? I think these days most
people<br>
(including myself) are going to end up looking at docs in the
'gems'<br>
area, making this feature less useful if it only applies to the<br>
'github' area.</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T21:30:36Z2011-10-21T21:30:36Zsuggestion: links back to github<div><p>Right, this would be a github specific thing.</p>
<p>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 <em>wrong</em>, 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.</p>
<p>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
<code>window.location.pathname</code>, not the host/port.</p></div>lsegaltag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T22:10:34Z2011-10-21T22:10:34Zsuggestion: links back to github<div><p>Okay, here's some JS that works. (There's probably a more
cleverly<br>
idiomatic functional jquery way to do this, but this seems good
enough<br>
to me). It even seems to work on "attributes" not just methods,
which<br>
I wasn't expecting, but your DOM is consistent in nice ways so
it<br>
surprised me and added links to github that worked there too,
woo.</p>
<p>I haven't actually cloned the repo or gotten my own server
started, I<br>
just did this JS greasemonkey-style. I have to admit my enthusiasm
is<br>
sapped realizing that this will only apply to the 'github'
section,<br>
when most of my use of rubydoc.info is actually the 'gem' section,
and<br>
I assume most other users the same. Too bad the rubygems<br>
infrastructure isn't quite good enough to support this for
'gems'<br>
section, I think (and if it was, it would require some actual
back-end<br>
changes to your code, not just JS, probably).</p>
<p>So do with it what you will! It is pretty cool, if nothing else
maybe<br>
i'll make a javascript bookmarklet for myself that applies it, for
the<br>
minority of times I'm looking at 'github' area rather than
'gems'<br>
area, alas! Thanks for your hints and feedback.</p>
<hr>
<p>if (match =
window.location.pathname.match(/<sup>\/github\/([<sup>\/]+\/[<sup>/]+)<br></sup></sup></sup>
\/([<sup>/]+)/))</sup> { var github_project = match[1]; var
github_commit = match[2];</p>
<p>$(".source_code").each( function() {</p>
<pre>
<code> if (match = $(this).find(".info.file").text().match(/^# File</code>
</pre>
<p>'([<sup>']+)',</sup> line (\d+)/)) {</p>
<pre>
<code> 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>');
}</code>
</pre>
<p>}); }</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T22:34:10Z2011-10-21T22:34:11Zsuggestion: links back to github<div><p>sorry, email to ticketing system bad for code. if anyone wants
to do anything with it, it's here: <a href=
"https://gist.github.com/1305162">https://gist.github.com/1305162</a></p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T22:35:48Z2011-10-21T22:35:50Zsuggestion: links back to github<div><p>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.</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T22:36:15Z2011-10-21T22:36:15Zsuggestion: links back to github<div><p>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!</p>
<p>I'll close this issue here, we can track it on github if you
open it there.</p>
<p>Loren</p></div>lsegaltag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T22:39:45Z2011-10-21T22:39:45Zsuggestion: links back to github<div><p>Where do I find the rubydoc.info tracker? I thought this WAS
that,<br>
since it's where the link from rubydoc.info "help" took me!<br>
rubydoc.info on github?</p></div>Jonathan Rochkindtag:rubydoc.tenderapp.com,2010-12-26:Comment/107931652011-10-21T22:40:57Z2011-10-21T22:40:57Zsuggestion: links back to github<div><p>Yes, sorry, I meant the <a href=
"http://github.com/lsegal/rubydoc.info/issues">http://github.com/lsegal/rubydoc.info/issues</a>
page. Since this is code related, and not "the site is down!"
related :)</p></div>lsegal