[ANN] Rubypub.com - A Ruby Documentation Wiki
Brian Tol
Rubypub.com is custom-built documentation wiki for Ruby Gems. Features of note:
1. It's loosely based on rdoc's HTML output, although hopefully a bit
nicer to look at.
2. Every README, module/class rdoc and method rdoc is editable. Other
files (docs, mostly) are included, too, though not in edible form.
3. 7,134 total gems are available, with 1,817 being newest releases.
New gems are imported nightly.
4. Every file from every gem is included at files.rubypub.com, and all
the Ruby files are HTMLized [1].
Rubypub's hopes/dreams are twofold:
1. Provide a single-source web site for Gem documentation, making it
easier for Ruby programmers to find documentation. It also offloads a
bit of work from gem authors: they don't need to remember to publish
their rdocs.
2. Allow everyone to easily contribute documentation, and offer that
documentation back to gem authors for incorporation into their
codebases and online docs.
Rubypub is part labor of love, part social experiment. The best case
scenario: it allows the ruby community to produce incredible
documentation extremely fast. Worse case: it makes bad documentation
worse.
There's a few bugs, and probably more than a few warts, but it's
hopefully far enough along to get feedback.
Near-term goals:
1. Nail down the licensing policy. Currently user-contributed
documentation is distributed under a Creative Commons
Attribution-ShareAlike 3.0 Unported Licence, except where doing so
would conflict with the original licensing terms. This seems fair, but
feedback is very much appreciated, as I'm not a licensing guru.
2. Stamp out the bugs and finish a few outstanding features. Please
use the Rubypub Google Group [2] to submit issues and submit ideas.
3. Figure out the best method of delivering contributed docs to
authors. XML? JSON? Patches? Ideas are appreciated.
One final note: Hopefully people find this useful. But if you're a gem
author and would prefer not to include your gems at rubypub, I'm happy
to remove them. Just drop me an email.
[1] Here's a sample:
http://files.rubypub.com/activesupport-1.4.2/lib/active_support.rb
[2] http://groups.google.com/group/rubypub
Ken Bloom
> [ANN] Rubypub.com - A Ruby Documentation Wiki
>
> Rubypub.com is custom-built documentation wiki for Ruby Gems. Features
> of note:
This should be very helpful. Thank you for the site.
> There's a few bugs, and probably more than a few warts, but it's
> hopefully far enough along to get feedback.
>
> Near-term goals:
>
> 1. Nail down the licensing policy. Currently user-contributed
> documentation is distributed under a Creative Commons
> Attribution-ShareAlike 3.0 Unported Licence, except where doing so would
> conflict with the original licensing terms. This seems fair, but
> feedback is very much appreciated, as I'm not a licensing guru.
Easy: user-contributed documentation for a gem should be under the same
license as the original gem (either that, or it should be in the public
domain), that way the original author can incorporate good improvements
without needing to worry about licensing conflicts.
2. Stamp
> out the bugs and finish a few outstanding features. Please use the
> Rubypub Google Group [2] to submit issues and submit ideas. 3. Figure
> out the best method of delivering contributed docs to authors. XML?
> JSON? Patches? Ideas are appreciated.
http://rubypub.com/gem/SqlStatement-1.0.2/SQLStatement::Select/ has
issues with leading # signs showing up in documentation where they're not
supposed to, and where they didn't show up in rdoc-generated HTML.
> One final note: Hopefully people find this useful. But if you're a gem
> author and would prefer not to include your gems at rubypub, I'm happy
> to remove them. Just drop me an email.
On the whole, a very nice site.
--Ken
--
Ken Bloom. PhD candidate. Linguistic Cognition Laboratory.
Department of Computer Science. Illinois Institute of Technology.
http://www.iit.edu/~kbloom1/
Florian Gross
> authors. XML? JSON? Patches? Ideas are appreciated.
Patches sound most useful to me.
And this looks very, very great. Good work!
I could see this becoming an official part of the Ruby homepage.
Trans
Er.. there are all sorts of problems with that.
What if I use slightly different rdoc parameters?
What if I rdoc my app in separate sections?
What if I don't use rdoc?
In those cases this sight presents a very misleading depiction of my
application.
I say leave it to me to document my app, thanks. If you want to create
a tool to help me do that than great, maybe I'll use it, but give me
the choice. I think it's mildly poor taste to do little more than
deliver up other people's docs to make $ with google ads. And I don't
think the wiki feature is useful enough to justify it.
T.
Robert Dober
<snip>
>
> One final note: Hopefully people find this useful. But if you're a gem
> author and would prefer not to include your gems at rubypub, I'm happy
> to remove them. Just drop me an email.
include the doc of gems without any permission of the authors.
It would not make me very happy for sure...
Robert
--
[...] as simple as possible, but no simpler.
-- Attributed to Albert Einstein
Gregory Brown
> On Fri, 27 Jul 2007 10:35:56 +0900, Brian Tol wrote:
>
> > [ANN] Rubypub.com - A Ruby Documentation Wiki
> >
> > Rubypub.com is custom-built documentation wiki for Ruby Gems. Features
> > of note:
>
> This should be very helpful. Thank you for the site.
+1 this looks beautiful
> > There's a few bugs, and probably more than a few warts, but it's
> > hopefully far enough along to get feedback.
> >
> > Near-term goals:
> >
> > 1. Nail down the licensing policy. Currently user-contributed
> > documentation is distributed under a Creative Commons
> > Attribution-ShareAlike 3.0 Unported Licence, except where doing so would
> > conflict with the original licensing terms. This seems fair, but
> > feedback is very much appreciated, as I'm not a licensing guru.
>
> Easy: user-contributed documentation for a gem should be under the same
> license as the original gem (either that, or it should be in the public
> domain), that way the original author can incorporate good improvements
> without needing to worry about licensing conflicts.
In fact, you *need* to do this. You don't have the rights to assume
that documentation from gems are under any license other than what the
author stated for them, and if you choose something like CC by S/A
(which I think is a nice license), you'll need to be sure that every
single project you host is under license terms compatible with it, or
get permission from every author to license the combined works as
such. Sounds like a painful nightmare to me.
So your choices are to either have user contributions be under the
public domain or under the original license scheme. As a package
maintainer, I'd like to throw my vote towards the original license
scheme!
> 2. Stamp
> > out the bugs and finish a few outstanding features. Please use the
> > Rubypub Google Group [2] to submit issues and submit ideas. 3. Figure
> > out the best method of delivering contributed docs to authors. XML?
> > JSON? Patches? Ideas are appreciated.
Patches please. The XML and JSON won't be very helpful for quickly
applying the docs to my files.
Rob Sanheim
Rdoc and the core doc pages have languished for so long, so its
inevitable that we'll see new tools like rubypub or railsbrain.com
come up. It would be great for folks to also try to improve rdoc
itself, but I welcome something like rubypub if it at least improves
the l&f and usability of plain rdoc.
- Rob
--
http://robsanheim.com
Brian Tol
> include the doc of gems without any permission of the authors.
> It would not make me very happy for sure...
To be honest, that was my biggest hesitation in developing the site.
Pissing people off is the _last_ thing I want to do. On the other
hand, since (a) lots of gems need better (or _any_) documentation, and
(b) gems are licensed in such a way that allow for reuse like this, I
thought I'd give it a go.
Ideally I'd like to see a way for authors to opt-out of the system
upfront, so I don't even need to bother with importing and them
removing it.
-
Brian "Chip" Tol
http://www.wiremine.org
wire...@gmail.com
Brian Tol
> > license as the original gem (either that, or it should be in the public
> > domain), that way the original author can incorporate good improvements
> > without needing to worry about licensing conflicts.
>
> In fact, you *need* to do this. You don't have the rights to assume
> that documentation from gems are under any license other than what the
> author stated for them, and if you choose something like CC by S/A
> (which I think is a nice license), you'll need to be sure that every
> single project you host is under license terms compatible with it, or
> get permission from every author to license the combined works as
> such. Sounds like a painful nightmare to me.
>
> So your choices are to either have user contributions be under the
> public domain or under the original license scheme. As a package
> maintainer, I'd like to throw my vote towards the original license
> scheme!
That sounds great to me. Any other thoughts/suggestions?
> > 2. Stamp
> > > out the bugs and finish a few outstanding features. Please use the
> > > Rubypub Google Group [2] to submit issues and submit ideas. 3. Figure
> > > out the best method of delivering contributed docs to authors. XML?
> > > JSON? Patches? Ideas are appreciated.
>
> Patches please. The XML and JSON won't be very helpful for quickly
> applying the docs to my files.
+1. My thinking at this point is to export the docs via JSON, and then
use a tool to utilize this data for patches.
--
Brian Tol
> inevitable that we'll see new tools like rubypub or railsbrain.com
> come up. It would be great for folks to also try to improve rdoc
> itself, but I welcome something like rubypub if it at least improves
> the l&f and usability of plain rdoc.
Man, I couldn't agree more. BTW, I don't really see rubypub as a
competitor to rdocs. Like Trans pointed out, not everyone will want to
be included, and, anyways, Rubypub won't work well for all gems.
Gregory Brown
> To be honest, that was my biggest hesitation in developing the site.
> Pissing people off is the _last_ thing I want to do. On the other
> hand, since (a) lots of gems need better (or _any_) documentation, and
> (b) gems are licensed in such a way that allow for reuse like this, I
> thought I'd give it a go.
(b) isn't true. What makes you assume that?
*most* gems are licensed this way, but there is no restriction on what
licenses people use by RubyForge as of yet.
Brian Tol
> On 7/27/07, Brian Tol <wire...@gmail.com> wrote:
>
> > To be honest, that was my biggest hesitation in developing the site.
> > Pissing people off is the _last_ thing I want to do. On the other
> > hand, since (a) lots of gems need better (or _any_) documentation, and
> > (b) gems are licensed in such a way that allow for reuse like this, I
> > thought I'd give it a go.
>
> (b) isn't true. What makes you assume that?
Good to know. I looked through a couple hundred gems looking at
licenses before I started this thing, so that's where I got that idea,
and looked at this page:
http://rubyforge.org/softwaremap/trove_list.php?form_cat=13
The "Other/Proprietary License" licensed projects are either (a) dual
license under GPL, or (b) haven't released anything.
The remaining gems are released under public domain, CC, OSI-approved,
or Ruby licenses. From what I've read, and in talking with other
people, the CC, OSI and Ruby licenses would work with rubypub.
That all said, violating license terms is really antithetical to
rubypub's goals, so more feedback is appreciated. Violating licenses
doesn't help end-users, or gem authors.
--
Brian Tol
> licenses people use by RubyForge as of yet.
As a side note:
If nothing else, I hope rubypub can be a discussion starter within the
ruby community about how to best improve and share ruby documentation.
It seems to me that allowing more people to contribute and improve
docs is a good goal to have. As a believer of wikis, I think rubypub
is a good way to start doing this, but it's not the end-all or be-all.
Like I said in the announcement, it's a bit of a social experiment.
Licensing details, data flow and -- most fundamentally -- user
participation, are all unknowns at this point.
--
Tomas Pospisek's Mailing Lists
> [ANN] Rubypub.com - A Ruby Documentation Wiki
1. The top of the page contains the title and search bar. OK, good. Then
below are "Recently released gems", etc. The indexes are far, far away
at the bottom of the page.
Assumed that the most important things should be at the top and that
the most important thing is the gem's documentation then the indexes
should be at the top and not at the bottom of the page (or they could
also be one in a side bar or such).
2. When I go way down ;-), click on Gems A-Z, then on 'R' and then on
'Next page', then the page I get only contains the *following*
gem in addition to the previous ones and not the following page. Thus
what is happening is problably something like this:
gems_to_display = find(i=i+)
instead of:
gems_to_display = find(i = i + $NUMBER_OF_GEMS_PER_PAGE)
(I have cookies switched off by default)
*t
--
-----------------------------------------------------------
Tomas Pospisek
http://sourcepole.com - Linux & Open Source Solutions
-----------------------------------------------------------
James Britt
> On 7/27/07, Brian Tol <wire...@gmail.com> wrote:
> <snip>
>> One final note: Hopefully people find this useful. But if you're a gem
>> author and would prefer not to include your gems at rubypub, I'm happy
>> to remove them. Just drop me an email.
> Should it not be the other way around? It surprises me that you
> include the doc of gems without any permission of the authors.
> It would not make me very happy for sure...
Has GemJack gotten flack?
It, too, hosts Gem documentation, though without a wiki.
--
James Britt
www.ruby-doc.org - Ruby Help & Documentation
www.risingtidesoftware.com - Wicked Cool Coding
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.jamesbritt.com - Playing with Better Toys
James Britt
> [ANN] Rubypub.com - A Ruby Documentation Wiki
>
> Rubypub.com is custom-built documentation wiki for Ruby Gems.
What's it written in? Ruby?
Is the source code available?
Brian Tol
Yes! It's basically a rails app with some odds and ends added to
handle the importing process.
>
> Is the source code available?
Not yet. I'd like to clean up and release the rdoc => database engine,
which is a handy little piece of code.
-Brian
Gregory Brown
> On 7/27/07, Gregory Brown <gregory...@gmail.com> wrote:
> > On 7/27/07, Brian Tol <wire...@gmail.com> wrote:
> >
> > > To be honest, that was my biggest hesitation in developing the site.
> > > Pissing people off is the _last_ thing I want to do. On the other
> > > hand, since (a) lots of gems need better (or _any_) documentation, and
> > > (b) gems are licensed in such a way that allow for reuse like this, I
> > > thought I'd give it a go.
> >
> > (b) isn't true. What makes you assume that?
>
> Good to know. I looked through a couple hundred gems looking at
> licenses before I started this thing, so that's where I got that idea,
> and looked at this page:
>
> http://rubyforge.org/softwaremap/trove_list.php?form_cat=13
>
> The "Other/Proprietary License" licensed projects are either (a) dual
> license under GPL, or (b) haven't released anything.
>
> The remaining gems are released under public domain, CC, OSI-approved,
> or Ruby licenses. From what I've read, and in talking with other
> people, the CC, OSI and Ruby licenses would work with rubypub.
There are OSI approved licenses which would not be compatible with CC
S/A, or at least be disputed.
For example, if I use an academic license which restricts certain
things about modification, my code would be open source but not free
software, and that means that third parties may not have the right to
redistribute derived works when it comes to documentation.
These issues are not likely to be numerous, but definitely likely to
be a big mess which you should avoid (and easily can).
Phlip
Brian Tol wrote:
> Hopefully people find this useful. But if you're a gem
> author and would prefer not to include your gems at rubypub, I'm happy
> to remove them. Just drop me an email.
>
> [1] Here's a sample:
> http://files.rubypub.com/activesupport-1.4.2/lib/active_support.rb
Why isn't your sample an exemplary README, like this?
http://rubypub.com/gem/sparklines-0.4.5/
And could you submit your style system to RDoc, to save us from those four
dreary frames?
--
Phlip
http://www.oreilly.com/catalog/9780596510657/
^ assert_xpath
http://tinyurl.com/23tlu5 <-- assert_raise_message
Phlip
> Props!
Brian, since I wrote that 90 seconds ago, I have mailed two links to your
pages out to two co-workers, regarding our projects.
Major props!!
Ken Bloom
Just do an automatic check against the gem's listing on Rubyforge, and
make sure it's an open source license. If so, then you're free to put the
docs on your site (assuming you agree with the license yourself), and you
don't have to pay attention to the author's wishes in contradiction with
the license at all. (However, you may choose to do so as a courtesey.)
Gregory Brown
Open source does not (necessarily) mean freely modifiable. Please be
sure that if you do this, that the licenses you check for are
compatible with CC S/A, not all will be.