Question on organizing local RDoc documentation

Discussion in 'Ruby' started by Alexey Verkhovsky, Sep 24, 2004.

  1. My Ruby installation is a bit of a mess, especially so far as the
    documentation is concerned. I would like to give it some semblance of
    good order.

    Can someone suggest a nice way to organize and maintain both ri and HTML
    documentation for a Ruby installation, that includes built-in classes,
    standard library, thrd party libraries and a number of RubyGems?

    Say, you build the above said installation from scratch and want to
    generate documentation for everything - how do you actually do that?
    Where do you run rdoc, with what options, where do you place the output,
    etc?

    And then, when you add/upgrade/delete a library, what do you do in those
    cases?

    I promise to summarize the answers and write a short guideline (assuming
    that I will have something to summarize :).

    Alex
    Alexey Verkhovsky, Sep 24, 2004
    #1
    1. Advertising

  2. Alexey Verkhovsky

    James Britt Guest

    Alexey Verkhovsky wrote:

    > My Ruby installation is a bit of a mess, especially so far as the
    > documentation is concerned. I would like to give it some semblance of
    > good order.
    >
    > Can someone suggest a nice way to organize and maintain both ri and HTML
    > documentation for a Ruby installation, that includes built-in classes,
    > standard library, thrd party libraries and a number of RubyGems?



    Good question. My understanding is that gem docs are stored separate
    from any other docs; the gem doc server seems to only know about
    installed gems, not core or std-lib docs.


    >
    > Say, you build the above said installation from scratch and want to
    > generate documentation for everything - how do you actually do that?
    > Where do you run rdoc, with what options, where do you place the output,
    > etc?


    Well, I believe that the current configure script does not install docs
    by default. You may need to do this:

    ./configure --enable-install-doc

    I think, though, that this only docs the core classes, e.g., Array and
    String, but not REXML or anything for which you need to use 'require'.
    (But even this is not quite true, as doing this gets you ri info for
    YAML, but not for REXML, though both are technically in the std-lib.)

    So you should have at least all of the core classes, and then some small
    number of standard lib classes.


    You can also cd to the installed Ruby /lib directory and run rdoc there:
    cd path/to/lib
    rdoc --system

    Which will install ri files.

    I think simply running rdoc in the lib directory will generate the html
    files.

    >
    > And then, when you add/upgrade/delete a library, what do you do in those
    > cases?


    If it's a gem, then using 'gem uninstall' should remove the docs for the
    specified gem. But if you installed the code using cp or install.rb or
    the like then you may need to manually remove the docs (including
    tracking down the ri *.yaml files if they were generated).

    >
    > I promise to summarize the answers and write a short guideline (assuming
    > that I will have something to summarize :).



    That would be much appreciated, as would any comments, corrections, and
    suggestions on rdoc/ri best practices.

    (On a side note, I tried Google to find pages that discussed RDoc, and
    found countless pages *generated* by rdoc, as the default page title is,
    or was, "RDoc Documentation." Which makes finding actual RDoc
    documentation a bit harder.)


    James
    James Britt, Sep 24, 2004
    #2
    1. Advertising

  3. On Saturday, September 25, 2004, 5:28:53 AM, Alexey wrote:

    > My Ruby installation is a bit of a mess, especially so far as the
    > documentation is concerned. I would like to give it some semblance of
    > good order.


    > Can someone suggest a nice way to organize and maintain both ri and HTML
    > documentation for a Ruby installation, that includes built-in classes,
    > standard library, thrd party libraries and a number of RubyGems?


    I tend to use 'ri' for built-ins, http://ruby-doc.org/stdlib for the
    standard library (local copy of that page, actually), and gem_server
    for RubyGems.

    'rdocweb' is a RubyForge project I started whose intention is to
    generalise the code behind the stdlib site, so you can generate a
    similar-looking set of HTML documentation for any set of Ruby
    libraries. But it's low-priority and hasn't gone anywhere.

    > Say, you build the above said installation from scratch and want to
    > generate documentation for everything - how do you actually do that?
    > Where do you run rdoc, with what options, where do you place the output,
    > etc?


    To discover the answer to that question, you need two things:
    * RDoc knowledge, which can be gained by experimentation; and
    * a strategy, which I don't think has been discussed before, and
    which I attempt below

    > And then, when you add/upgrade/delete a library, what do you do in those
    > cases?


    How do you organise your Ruby libraries, etc? You could write a
    program that visits each source directory, runs RDoc, collects the
    results, and puts all the documentation behind a generated index page.
    Dump the final results into a nice location, bookmark it, and you're
    away.

    Then extend it to include gems (I or someone else can help with that
    when the time comes).

    Whenever you add or remove a library, run the whole lot again.
    Remembering some timestamps will help avoid expensive regeneration.

    That's your third-party stuff covered. Tie it in with a local copy of
    the core and stdlib stuff, and you'll be smiling.

    > I promise to summarize the answers and write a short guideline (assuming
    > that I will have something to summarize :).


    It may be you can write a generally-useful enough program to cover
    everyone's needs. The 'stdlib-doc' RubyForge project does some of this
    stuff. Feel free to ask about its innards if it seems useful.

    Cheers,
    Gavin
    Gavin Sinclair, Sep 25, 2004
    #3
  4. Alexey Verkhovsky

    Dave Thomas Guest

    On Sep 24, 2004, at 15:28, Alexey Verkhovsky wrote:

    > Can someone suggest a nice way to organize and maintain both ri and
    > HTML
    > documentation for a Ruby installation, that includes built-in classes,
    > standard library, thrd party libraries and a number of RubyGems?


    Alexy:

    Let's start with the 'ri' side of things.

    As you're installing from source, then you can arrange for the ri
    documentation for everything in the standard Ruby distribution to be
    generated at the time you build Ruby. There's some variance here,
    because the default of whether or not to generate this documentation
    changed between version of Ruby. So, in your Ruby source tree, you'd do
    a standard

    ./configure
    make
    make install

    If you don't see that generating the ri documentation at the end, add
    one more step

    make install-doc

    Then there's the libraries. If you use Gems, then I believe the latest
    will automatically manage installing the ri documentation. If you use
    rpa, I think it comes with a hacked version of ri that does the same
    thing.

    For libraries that you install manually, you can add ri documentation
    to your local tree using

    rdoc --ri <filelist>
    or
    rdoc --ri-site <filelist>

    The first form installs the documentation for your personal use, the
    second installs them site wide.

    When it comes to HTML documentation, the story is slightly different.
    ri keeps its documentation in a kind of database format. This allows me
    to add to it incrementally. For example, if a newly installed library
    adds a method to the String class, I can add that method in, and the
    next time you ask ri for a list of String's methods, that new method
    will appear.

    I can't easily do that with the HTML versions of the documentation. As
    a result, its hard to maintain a merged set of HTML documentation for
    things that you add over time.

    I'm thinking of a fix to this, which would involve generating a site
    HTML documentation tree from the ri database. This would give you what
    you want (I believe). Until then, I'd stick with ri for unified
    documentation and use RDoc for documentating individual modules.


    Cheers

    Dave
    Dave Thomas, Sep 25, 2004
    #4
  5. Alexey Verkhovsky

    Chad Fowler Guest

    On Sun, 26 Sep 2004 01:54:29 +0900, Dave Thomas <> wrote:

    > Then there's the libraries. If you use Gems, then I believe the latest
    > will automatically manage installing the ri documentation. If you use
    > rpa, I think it comes with a hacked version of ri that does the same
    > thing.
    >


    Unfortunately, Gems still doesn't do ri. Dave, Mauricio and I started
    discussing how best to do ri generation for separate package managers,
    but we have yet to come to a great conclusion. (Yes, I realize I'm
    replying to Dave in the 3rd person ;).

    We had ri generation in temporarily but took it out for 0.8.1. We'll
    include it in the next release.

    Chad
    Chad Fowler, Sep 25, 2004
    #5
  6. On Sun, Sep 26, 2004 at 01:54:29AM +0900, Dave Thomas wrote:
    > If you don't see that generating the ri documentation at the end, add
    > one more step
    >
    > make install-doc
    >
    > Then there's the libraries. If you use Gems, then I believe the latest
    > will automatically manage installing the ri documentation. If you use
    > rpa, I think it comes with a hacked version of ri that does the same
    > thing.


    I think this has been disabled in RubyGems 0.8.x.
    The ri distributed by RPA as ri-rpa was patched to allow RI documentation
    to be removed on uninstall easily. It also includes pre-generated ri
    documentation (so that one doesn't have to download Ruby's sources and
    generate them manually).

    --
    Running Debian GNU/Linux Sid (unstable)
    batsman dot geo at yahoo dot com
    Mauricio Fernández, Sep 26, 2004
    #6
    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. Andreas Schwarz
    Replies:
    6
    Views:
    238
    Randy W. Sims
    Jan 1, 2004
  2. Brian Schröder
    Replies:
    5
    Views:
    121
    Dave Thomas
    Sep 18, 2004
  3. Daniel Berger
    Replies:
    1
    Views:
    136
    Dave Thomas
    Nov 2, 2004
  4. Iwan van der Kleyn

    rdoc: how to add readme.rdoc as index.html?

    Iwan van der Kleyn, Apr 26, 2005, in forum: Ruby
    Replies:
    1
    Views:
    214
    Stefan Lang
    Apr 26, 2005
  5. Jesper Rønn-Jensen
    Replies:
    4
    Views:
    124
    Joel VanderWerf
    Feb 22, 2008
Loading...

Share This Page