[ANN] Rubypub.com - A Ruby Documentation Wiki

Discussion in 'Ruby' started by Brian Tol, Jul 27, 2007.

  1. Brian Tol

    Brian Tol Guest

    [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_support.rb
    [2] http://groups.google.com/group/rubypub
     
    Brian Tol, Jul 27, 2007
    #1
    1. Advertising

  2. Brian Tol

    Phlip Guest

    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_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, Jul 27, 2007
    #2
    1. Advertising

  3. Brian Tol

    Phlip Guest

    Phlip, Jul 27, 2007
    #3
  4. Re: Rubypub.com - A Ruby Documentation Wiki

    > 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.
     
    Florian Gross, Jul 27, 2007
    #4
  5. Brian Tol

    Trans Guest

    Re: Rubypub.com - A Ruby Documentation Wiki

    On Jul 27, 7:50 am, Florian Gross <> 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.
     
    Trans, Jul 27, 2007
    #5
  6. Brian Tol

    Robert Dober Guest

    On 7/27/07, Brian Tol <> 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
     
    Robert Dober, Jul 27, 2007
    #6
  7. On 7/27/07, Ken Bloom <> 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.
     
    Gregory Brown, Jul 27, 2007
    #7
  8. Brian Tol

    Rob Sanheim Guest

    Re: Rubypub.com - A Ruby Documentation Wiki

    On 7/27/07, Trans <> wrote:
    >
    >
    > On Jul 27, 7:50 am, Florian Gross <> 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://robsanheim.com
     
    Rob Sanheim, Jul 27, 2007
    #8
  9. Brian Tol

    Brian Tol Guest

    > 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.wiremine.org
     
    Brian Tol, Jul 27, 2007
    #9
  10. Brian Tol

    Brian Tol Guest

    > > 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.wiremine.org
     
    Brian Tol, Jul 27, 2007
    #10
  11. Brian Tol

    Brian Tol Guest

    Re: Rubypub.com - A Ruby Documentation Wiki

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


    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.

    --
    Brian "Chip" Tol
    http://www.wiremine.org
     
    Brian Tol, Jul 27, 2007
    #11
  12. On 7/27/07, Brian Tol <> 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?

    *most* gems are licensed this way, but there is no restriction on what
    licenses people use by RubyForge as of yet.
     
    Gregory Brown, Jul 27, 2007
    #12
  13. Brian Tol

    Brian Tol Guest

    On 7/27/07, Gregory Brown <> wrote:
    > On 7/27/07, Brian Tol <> 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 "Chip" Tol
    http://www.wiremine.org
     
    Brian Tol, Jul 27, 2007
    #13
  14. Brian Tol

    Brian Tol Guest

    > *most* gems are licensed this way, but there is no restriction on what
    > 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.

    --
    Brian "Chip" Tol
    http://www.wiremine.org
     
    Brian Tol, Jul 27, 2007
    #14
  15. Bug [was: Re: [ANN] Rubypub.com - A Ruby Documentation Wiki]

    On Fri, 27 Jul 2007, Brian Tol wrote:

    > [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
    -----------------------------------------------------------
     
    Tomas Pospisek's Mailing Lists, Jul 27, 2007
    #15
  16. Brian Tol

    James Britt Guest

    Robert Dober wrote:
    > On 7/27/07, Brian Tol <> 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?

    http://www.gemjack.com/

    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, Jul 27, 2007
    #16
  17. Brian Tol

    James Britt Guest

    Brian Tol wrote:
    > [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?

    --
    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, Jul 27, 2007
    #17
  18. Brian Tol

    Brian Tol Guest

    > What's it written in? Ruby?

    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

    --
    Brian "Chip" Tol
    http://www.wiremine.org
     
    Brian Tol, Jul 27, 2007
    #18
  19. On 7/27/07, Brian Tol <> wrote:
    > On 7/27/07, Gregory Brown <> wrote:
    > > On 7/27/07, Brian Tol <> 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).
     
    Gregory Brown, Jul 27, 2007
    #19
  20. Brian Tol

    Ken Bloom Guest

    On Sat, 28 Jul 2007 01:10:16 +0900, Brian Tol wrote:

    > On 7/27/07, Gregory Brown <> wrote:
    >> On 7/27/07, Brian Tol <> 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.


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

    --Ken

    --
    Ken Bloom. PhD candidate. Linguistic Cognition Laboratory.
    Department of Computer Science. Illinois Institute of Technology.
    http://www.iit.edu/~kbloom1/
     
    Ken Bloom, Jul 27, 2007
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. chris
    Replies:
    4
    Views:
    902
    chris
    May 17, 2004
  2. Eric @ Zomething

    Python Wiki & wiki Hosting?

    Eric @ Zomething, Jun 5, 2004, in forum: Python
    Replies:
    2
    Views:
    546
  3. Eric S. Johansson

    Re: Python Wiki & wiki Hosting?

    Eric S. Johansson, Jun 6, 2004, in forum: Python
    Replies:
    6
    Views:
    517
    Paul Boddie
    Jun 8, 2004
  4. Mahrt, Dallas

    RE: Python Wiki & wiki Hosting?

    Mahrt, Dallas, Jun 7, 2004, in forum: Python
    Replies:
    0
    Views:
    432
    Mahrt, Dallas
    Jun 7, 2004
  5. Robert Oschler

    Wiki engine used by Ruby Wiki?

    Robert Oschler, Jun 17, 2004, in forum: Ruby
    Replies:
    3
    Views:
    238
    Erik Veenstra
    Jun 25, 2004
Loading...

Share This Page