Problem setting main file for rdoc

Discussion in 'Ruby' started by James Britt, Sep 11, 2004.

  1. James Britt

    James Britt Guest

    I'm running ruby 1.8.2 (2004-07-29) [i386-mswin32] with RDoc V1.0pr1:
    2004/04/04 23:19:58 (1.1.2.6) on Win2k.

    My project layout has the main code in lib\OOo4R, I want my docs in
    doc\, and I want the main doc file to be lib\OOo4R\OOo.rb, so from the
    root directory of my project I ran


    D:\development\RubyForge\ooo4r>rdoc -m lib\OOo4R\OOo.rb lib\OOo4R

    It creates the rdoc files fine, so it has no problem finding the
    lib\OOo4R directory, but I get these messages along the way:

    Generating HTML...
    Could not find main page lib\OOo4R\OOo.rb
    Could not find main page lib\OOo4R\OOo.rb
    Could not find main page lib\OOo4R\OOo.rb
    Could not find main page lib\OOo4R\OOo.rb

    But it finds that file well enough to doc it along with the other files
    in the given path.

    If I leave off the directory path and just give the file name (OOo.rb),
    I get a similar set of messages. Using a complete file path doesn't
    help; neither does full-path using unix-style forward slashes.

    The rdoc help just says
    --main, -m name 'name' will be the initial page displayed

    but says nothing about specifying the path to the file.

    (I'm guessing that 'name' refers to the name of the source file, though
    I suppose it could mean the name of the generated page, or the name of a
    class or module.)

    What's the correct syntax?


    Thanks,


    James
    James Britt, Sep 11, 2004
    #1
    1. Advertising

  2. James Britt

    Dave Thomas Guest

    On Sep 10, 2004, at 22:26, James Britt wrote:

    > D:\development\RubyForge\ooo4r>rdoc -m lib\OOo4R\OOo.rb lib\OOo4R


    Try using the name of a class in the main file.

    Cheers

    Dave
    Dave Thomas, Sep 11, 2004
    #2
    1. Advertising

  3. James Britt

    James Britt Guest

    Dave Thomas wrote:
    >
    > On Sep 10, 2004, at 22:26, James Britt wrote:
    >
    >> D:\development\RubyForge\ooo4r>rdoc -m lib\OOo4R\OOo.rb lib\OOo4R

    >
    >
    > Try using the name of a class in the main file.


    I got it working by using
    rdoc -m OOo::Doc lib\OOo4R

    Thanks; there is no way I would have guessed this from the rdoc
    command-line help, though.

    Suppose I want to have a general-info page (e.g. README.rdoc) be the
    main page, or if several files define different parts of the same class?

    Is there some way to simply say, "Rdoc this arbitrary file and set it
    as the main page"?


    Thanks,

    James
    James Britt, Sep 11, 2004
    #3
  4. James Britt

    Dave Thomas Guest

    On Sep 11, 2004, at 7:21, James Britt wrote:
    > Is there some way to simply say, "Rdoc this arbitrary file and set it
    > as the main page"?


    Does putting it as the first file on the command line not work?

    Cheers

    Dave
    Dave Thomas, Sep 11, 2004
    #4
  5. James Britt

    James Britt Guest

    Dave Thomas wrote:

    >
    > On Sep 11, 2004, at 7:21, James Britt wrote:
    >
    >> Is there some way to simply say, "Rdoc this arbitrary file and set it
    >> as the main page"?

    >
    >
    > Does putting it as the first file on the command line not work?



    That was what I was trying at first. There is a specific Ruby source
    file I wanted to serve as the main doc page, so passed the path as the
    first file. But none of the paths made rdoc happy.

    Passing in the name of a class worked, but that likely won't help for a
    general text file.

    As an experiment, I tried to specify a file in the current directory
    (while rdocing code in a subdirectory):

    rdoc -m README.txt lib\OOo4R

    The file README.txt exists in the current directory, but rdoc reports
    that it cannot find it.

    rdoc -m ./README.txt lib\OOo4R

    doesn't work either (nor .\README.txt). Even passing in the complete
    windows file path does not help.

    But, on re-reading your suggestion, I tried again, omitting the -m and
    just passing in the relative path to README.txt as the first argument.

    This works, but seems a little counter-intuitive, given that the
    command-line help says to use " -m name " to set the initial page

    My understanding now is to use "-m fully_qualified_name_of_class" to
    have the file defining that class appear as the initial page, or leave
    out the -m and just pass the path to the disk file to be used (after
    rdoc'ing) as the initial file.

    Question: If I pass rdoc a complete list of files, rather than a
    directory, will the files appear in list order in the Files frames?

    That could be handy for pushing boring, least-used docs to the bottom.


    Thanks,


    James


    >
    > Cheers
    >
    > Dave
    >
    >
    >
    James Britt, Sep 11, 2004
    #5
  6. James Britt

    Dave Thomas Guest

    On Sep 11, 2004, at 8:57, James Britt wrote:

    >>> page"?

    >> Does putting it as the first file on the command line not work?

    >
    >
    > That was what I was trying at first. There is a specific Ruby source
    > file I wanted to serve as the main doc page, so passed the path as the
    > first file. But none of the paths made rdoc happy.


    > rdoc -m README.txt lib\OOo4R


    The first regular file is the main file in the absence of a -m

    rdoc README.txt lib\OOo4R

    > This works, but seems a little counter-intuitive, given that the
    > command-line help says to use " -m name " to set the initial page


    The doc also says that the first file is the deault main file.,,

    Cheers

    Dave
    Dave Thomas, Sep 11, 2004
    #6
  7. James Britt

    James Britt Guest

    Dave Thomas wrote:
    >
    >
    >
    > The doc also says that the first file is the deault main file.,,



    Does this appear in the command line help?

    I don't see it when I run rdoc -help, though maybe I'm just misreading it.


    Thanks,


    James
    James Britt, Sep 11, 2004
    #7
    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:
    243
    Randy W. Sims
    Jan 1, 2004
  2. Brian Schröder
    Replies:
    5
    Views:
    129
    Dave Thomas
    Sep 18, 2004
  3. Daniel Berger
    Replies:
    1
    Views:
    139
    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:
    221
    Stefan Lang
    Apr 26, 2005
  5. Jesper Rønn-Jensen
    Replies:
    4
    Views:
    128
    Joel VanderWerf
    Feb 22, 2008
Loading...

Share This Page