[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

[ANN] Rubypub.com - A Ruby Documentation Wiki

Brian Tol

7/27/2007 1:36:00 AM

[ANN] Rubypub.com - A Ruby Documentation Wiki

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_...
[2] http://groups.google.com/gro...
22 Answers

Ken Bloom

7/27/2007 2:08:00 PM

0

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.

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

Phlip

7/27/2007 2:38:00 PM

0

Props!!

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

Why isn't your sample an exemplary README, like this?

http://rubypub.com/gem/sparkli...

And could you submit your style system to RDoc, to save us from those four
dreary frames?

--
Phlip
http://www.oreilly.com/catalog/9780...
^ assert_xpath
http://tinyurl.... <-- assert_raise_message

Phlip

7/27/2007 2:41:00 PM

0

Phlip wrote:

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

--
Phlip
http://www.oreilly.com/catalog/9780...
^ assert_xpath
http://tinyurl.... <-- assert_raise_message

Florian Groß

7/27/2007 2:51:00 PM

0

> 3. Figure out the best method of delivering contributed docs to
> 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

7/27/2007 3:08:00 PM

0



On Jul 27, 7:50 am, Florian Gross <flor...@gmail.com> wrote:
> > 3. Figure out the best method of delivering contributed docs to
> > 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.

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

7/27/2007 3:22:00 PM

0

On 7/27/07, Brian Tol <wiremine@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...

Robert

--
[...] as simple as possible, but no simpler.
-- Attributed to Albert Einstein

Gregory Brown

7/27/2007 3:24:00 PM

0

On 7/27/07, Ken Bloom <kbloom@gmail.com> wrote:
> 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

7/27/2007 3:27:00 PM

0

On 7/27/07, Trans <transfire@gmail.com> wrote:
>
>
> On Jul 27, 7:50 am, Florian Gross <flor...@gmail.com> wrote:
> > > 3. Figure out the best method of delivering contributed docs to
> > > 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.
>
> 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.

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://robs...

Brian Tol

7/27/2007 3:31:00 PM

0

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

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.wi...
wiremine@gmail.com

Brian Tol

7/27/2007 3:33:00 PM

0

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

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 "Chip" Tol
http://www.wi...
wiremine@gmail.com