From: Eric Hodel <drbrain@...7.net>
Date: 2009-02-26T02:35:47+09:00
Subject: Re: How does one generate a "main page" for rdoc documentation?


On Feb 19, 2009, at 15:41, 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

this is file documentation

>  * (2) any comments preceding all classes

this is class documentation

>  * (3) any comments before the methods you define

this is method documentation

> This means your Ruby programs must have the following format:
> [...]

This is not how RDoc works:

$ find . -type f
./lib/foo.rb
$ rdoc .
Parsing sources with 2 thread(s)...
100% [ 1/ 1]  lib/foo.rb

Generating Darkfish...

Files:   1
Classes: 1
Modules: 0
Methods: 1
Elapsed: 0.0s
$ ack 'My application' doc/index.html
[no results]
$

You need to specify --main to have content beyond the generic "This is  
the API documentation for 'RDoc Documentation'." show up in doc/ 
index.html.  Usually this is done like this:

$ find . -type f
./lib/foo.rb
./README
$ cat README
# =Your Application Documentation
#
# My application does this and that, and
# much more ......
#
# ==Subtile #1
#
# xyzxyzxyz xyzxyzxyz  xyzxy xyzxyzxyz x
# xyzxyzxyz xyzxyzxyz xyzxyzxyz xyzxyzxy
# xyzxyzxyz xyzx
#
$ rdoc . --main README
[...]
$ ack 'My application' doc/index.html
My application does this and that, and much more .&#8230;..