Asp Forum - How does one generate a "main page" for rdoc documentation?

Kenneth McDonald

2/19/2009 9:25:00 PM

I tried

rdoc --main maindocpage rex.rb

where both maindocpage and rex.rb were in the current directory, and
got the message:

Could not find main page maindocpage

multiple times.

Thanks,
Ken

20 Answers

Kenneth McDonald

2/19/2009 9:34:00 PM

An additional note: adding a .rb suffix to the filename and command
line did not help.

Thanks,
Ken

On Feb 19, 2009, at 3:24 PM, Kenneth McDonald wrote:

> I tried
>
> rdoc --main maindocpage rex.rb
>
> where both maindocpage and rex.rb were in the current directory, and
> got the message:
>
> Could not find main page maindocpage
>
> multiple times.
>
> Thanks,
> Ken
>

Rick DeNatale

2/19/2009 11:11:00 PM

[Note: parts of this message were removed to make it a legal post.]

On Thu, Feb 19, 2009 at 4:24 PM, Kenneth McDonald <
kenneth.m.mcdonald@sbcglobal.net> wrote:

> I tried
>
> rdoc --main maindocpage rex.rb
>
> where both maindocpage and rex.rb were in the current directory, and got
> the message:
>
> Could not find main page maindocpage
>
> multiple times.
>
> Thanks,
> Ken
>
>
Without any other hint, rdoc only looks at .rb files for input, so although
it might seem redundant try

rdoc --main maindocpage maindocpage rex.rb

--
Rick DeNatale

Blog: http://talklikeaduck.denh...
Twitter: http://twitter.com/Ri...
WWR: http://www.workingwithrails.com/person/9021-ric...
LinkedIn: http://www.linkedin.com/in/ri...

Joel VanderWerf

2/19/2009 11:28:00 PM

Rick DeNatale wrote:
> On Thu, Feb 19, 2009 at 4:24 PM, Kenneth McDonald <
> kenneth.m.mcdonald@sbcglobal.net> wrote:
>
>> I tried
>>
>> rdoc --main maindocpage rex.rb
>>
>> where both maindocpage and rex.rb were in the current directory, and got
>> the message:
>>
>> Could not find main page maindocpage
>>
>> multiple times.
>>
>> Thanks,
>> Ken
>>
>>
> Without any other hint, rdoc only looks at .rb files for input, so although
> it might seem redundant try
>
> rdoc --main maindocpage maindocpage rex.rb

I think you're right. Looking at all of my script to generate rdocs, I
find exactly that redundancy, for example:

rdoc -m README ... lib/**/*.rb README

--
vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

Igor Pirnovar

2/19/2009 11:42:00 PM

Where did you get the syntax for your:
+---------------------------------+
| rdoc --main maindocpage rex.rb |
+---------------------------------+

The only thing you need is run rdoc without any arguments (parameters)
in a directory where is your documented Ruby program; i.e.: cd into that
directory! This command (rdoc) will create the HTML documentation in the
"doc" directory in the same directory where you placed your "rex.rb" and
where you have executed rdoc. in other words, after execution of rdoc
look for "./doc/index.html". This is your main documentation page
including all dependent Ruby files your "rex.rb" may have.

What you think is the "maindocpage" is most likely the initial
documentation for your application, and it is part of the commented text
in front of your "rex.rb".

rdoc extracts three different kinds of info from your Ruby file:

* (1) header or main documentation at the very beginning immediately
after the shebang
* (2) any comments preceding all classes
* (3) any comments before the methods you define

This means your Ruby programs must have the following format:

+------------------------------------------+
01 | #!/usr/bin/env ruby |
02 | | (1)
03 | # =Your Application Documentation | <-- Main doc. what
04 | # | you must likely
05 | # My application does this and that, and | mistakenly have
06 | # much more ...... | in a separate
07 | # | file (maindocpage)
08 | # ==Subtile #1 |
09 | # |
10 | # xyzxyzxyz xyzxyzxyz xyzxy xyzxyzxyz x |
11 | # xyzxyzxyz xyzxyzxyz xyzxyzxyz xyzxyzxy |
12 | # xyzxyzxyz xyzx |
13 | # | (2)
14 | | <-- empty line
15 | # ==My First Class | separates main
16 | # xyzxyzxyz xyzxyzxyz xyzxy xyzxyzxyz x | doc. from class
17 | # xyzxyzxyz xyzxyzxyz xyzxyzxyz xyzxyzxy | docunentation
18 | # xyzxyzxyz xyzx |
19 | |
20 | class MyFirstClass |
21 | ... |
22 | | (3)
23 | # This method does this and that, when | <-- Method doc
24 | # you pass it both parameters ... | preceding any
25 | | methods defined
26 | def a_method(p1, p2) | within a class
27 | ... |
28 | end |
29 | end |
30 +------------------------------------------+
--
Posted via http://www.ruby-....

Tom Cloyd

2/20/2009 12:49:00 AM

Igor Pirnovar wrote:
> Where did you get the syntax for your:
> +---------------------------------+
> | rdoc --main maindocpage rex.rb |
> +---------------------------------+
>
> The only thing you need is run rdoc without any arguments (parameters)
> in a directory where is your documented Ruby program; i.e.: cd into that
> directory! This command (rdoc) will create the HTML documentation in the
> "doc" directory in the same directory where you placed your "rex.rb" and
> where you have executed rdoc. in other words, after execution of rdoc
> look for "./doc/index.html". This is your main documentation page
> including all dependent Ruby files your "rex.rb" may have.
>
> What you think is the "maindocpage" is most likely the initial
> documentation for your application, and it is part of the commented text
> in front of your "rex.rb".
>
> rdoc extracts three different kinds of info from your Ruby file:
>
> * (1) header or main documentation at the very beginning immediately
> after the shebang
> * (2) any comments preceding all classes
> * (3) any comments before the methods you define
>
> This means your Ruby programs must have the following format:
>
> +------------------------------------------+
> 01 | #!/usr/bin/env ruby |
> 02 | | (1)
> 03 | # =Your Application Documentation | <-- Main doc. what
> 04 | # | you must likely
> 05 | # My application does this and that, and | mistakenly have
> 06 | # much more ...... | in a separate
> 07 | # | file (maindocpage)
> 08 | # ==Subtile #1 |
> 09 | # |
> 10 | # xyzxyzxyz xyzxyzxyz xyzxy xyzxyzxyz x |
> 11 | # xyzxyzxyz xyzxyzxyz xyzxyzxyz xyzxyzxy |
> 12 | # xyzxyzxyz xyzx |
> 13 | # | (2)
> 14 | | <-- empty line
> 15 | # ==My First Class | separates main
> 16 | # xyzxyzxyz xyzxyzxyz xyzxy xyzxyzxyz x | doc. from class
> 17 | # xyzxyzxyz xyzxyzxyz xyzxyzxyz xyzxyzxy | docunentation
> 18 | # xyzxyzxyz xyzx |
> 19 | |
> 20 | class MyFirstClass |
> 21 | ... |
> 22 | | (3)
> 23 | # This method does this and that, when | <-- Method doc
> 24 | # you pass it both parameters ... | preceding any
> 25 | | methods defined
> 26 | def a_method(p1, p2) | within a class
> 27 | ... |
> 28 | end |
> 29 | end |
> 30 +------------------------------------------+
>
Igor, this is very nice. Thanks for taking the time to write it up. I'm
putting a copy of it in my Ruby notes immediately.

Tom

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Joel VanderWerf

2/20/2009 12:53:00 AM

Igor Pirnovar wrote:
> What you think is the "maindocpage" is most likely the initial
> documentation for your application, and it is part of the commented text
> in front of your "rex.rb".
>
> rdoc extracts three different kinds of info from your Ruby file:
>
> * (1) header or main documentation at the very beginning immediately
> after the shebang
> * (2) any comments preceding all classes
> * (3) any comments before the methods you define

That's not the only way to do things. I like a separate README so that
someone can find a top-level, greppable help file without going to the
rdoc or digging in lib/. Also, I don't like all that extra front matter
in my class definitions.

--
vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

James Britt

2/20/2009 2:35:00 AM

ThoML

2/20/2009 4:40:00 AM

> > | rdoc --main maindocpage rex.rb |
> Without telling rdoc what files to treat as "main", you may be surprised
> which file it picks if you have more than one.

According to the Pickaxe3, there is a :main: directive that can be
used instead of the command line. IIRC the rdoc that shipped with ruby
1.8.7 didn't support that directive though.

James Britt

2/20/2009 6:40:00 AM

Tom Link wrote:
>>> | rdoc --main maindocpage rex.rb |
>> Without telling rdoc what files to treat as "main", you may be surprised
>> which file it picks if you have more than one.
>
> According to the Pickaxe3, there is a :main: directive that can be
> used instead of the command line. IIRC the rdoc that shipped with ruby
> 1.8.7 didn't support that directive though.

Thanks.

Do you know if this is supported by the Rdoc gem?

--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff

ThoML

2/20/2009 5:47:00 PM

> Do you know if this is supported by the Rdoc gem?

Ha ha, I took a look at the code. The directive is actually supported
but you have to put it into a ruby file. If you put it into a text
file, you get an unknown directive error. For whatever reason ... oh
well.

A line like

# :main: README.TXT

in some ruby file should set the main page to README.TXT.

comp.lang.ruby

How does one generate a "main page" for rdoc documentation?

Kenneth McDonald

Kenneth McDonald

Rick DeNatale

Joel VanderWerf

Igor Pirnovar

Tom Cloyd

Joel VanderWerf

James Britt

ThoML

James Britt

ThoML

x Login to ForumsZone