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


#1

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


#2

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

Thanks,
Ken


#3

On Thu, Feb 19, 2009 at 4:24 PM, Kenneth McDonald <
removed_email_address@domain.invalid> wrote:

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.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
WWR: http://www.workingwithrails.com/person/9021-rick-denatale
LinkedIn: http://www.linkedin.com/in/rickdenatale


#4

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 ±-----------------------------------------+


#5

Rick DeNatale wrote:

   Could not find main page maindocpage

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


#6

Igor P. wrote:

look for “./doc/index.html”. This is your main documentation page

  • (2) any comments preceding all classes
    06 | # much more … | in a separate
    17 | # xyzxyzxyz xyzxyzxyz xyzxyzxyz xyzxyzxy | docunentation
    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 C., MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< removed_email_address@domain.invalid >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)

#7

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


#8

Igor P. wrote:

look for “./doc/index.html”. This is your main documentation page
including all dependent Ruby files your “rex.rb” may have.

Without telling rdoc what files to treat as “main”, you may be surprised
which file it picks if you have more than one.


James B.

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


#9

Tom L. 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 B.

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


#10

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


#11

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.


#12

Igor P. wrote:

is to convert the in-line comments to external documentation.
@facepalm = true


James B.

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


#13

James B. wrote:

Without telling rdoc what files to treat as “main”, you
may be surprised which file it picks if you have more
than one.

You must be a rather disorganized computer … Each project that
deserves to be processed with rdoc should be in a separate directory,
and there will be absolutely no surprise what file rdoc will pick up.
All of you guys seem to have missed the main idea behind the rdoc, which
is to convert the in-line comments to external documentation.

Joel VanderWerf wrote:

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.

The rdoc package documents have three sections: Files, Classes and
Methods, and for each of them rdoc creates a separate “html” file which
are then managed from the top level index.html. The file level / header
documentation may be included in every file an is what is what I above
called the application doc. All these different pieces of info are
displayed under the Files, Classes, and Methods sections at the top of
the rdoc web-page, so you can choose what you are interested in by
clicking on the individual items there. Indeed, you can create a
README.rb, HEADER.rb or anything you like to pack in and squirrel away
the header (application level) documentation, but that defeats the
original rdoc strategy which is document as you go - converting the
in-line comments to documentation. If you follow the rdoc rules you will
end-up with a pretty decent documentation without the need for too much
extra efforts, as long as you have the discipline to document what you
are doing.

That is how rdoc works, and there isn’t very much you can do about it.
Yes, I would like it to provide a directive to include images, for
instance, I sometimes add class and object diagrams, but in order to do
that you have to tweak the doc/*.html. In fact, one day I may add just
such an extension for rdoc myself, unless someone else doesn’t take my
advice and does it for me :wink:


#14

On Fri, Feb 20, 2009 at 12:50 PM, Igor P. removed_email_address@domain.invalid
wrote:

That is how rdoc works, and there isn’t very much you can do about it.
Yes, I would like it to provide a directive to include images, for
instance, I sometimes add class and object diagrams, but in order to do
that you have to tweak the doc/*.html. In fact, one day I may add just
such an extension for rdoc myself, unless someone else doesn’t take my
advice and does it for me :wink:

Umm, you can include some of this via rdoc markup, e.g. from the rdoc
rdoc

Hyperlinks to the web starting http:, mailto:, ftp:, or www. are
recognized.
An HTTP url that references an external image file is converted into an
inline <IMG…>. Hyperlinks starting ‘link:’ are assumed to refer to
local
files whose path is relative to the --op directory.

And there are lots of options which affect what it outputs.

$ rdoc --help

RDoc V1.0.1 - 20041108

Usage:

rdoc [options] [names…]

Files are parsed, and the information they contain
collected, before any output is produced. This allows cross
references between all files to be resolved. If a name is a
directory, it is traversed. If no names are specified, all
Ruby files in the current directory (and subdirectories) are
processed.

Options:

  --accessor, -A accessorname[,..]
                        comma separated list of additional class 

methods
that should be treated like ‘attr_reader’
and
friends. Option may be repeated. Each
accessorname
may have ‘=text’ appended, in which case
that
text
appears where the r/w/rw appears for normal
accessors.

       --all, -a        include all methods (not just public)
                        in the output

   --charset, -c charset
                        specifies HTML character-set

     --debug, -D        displays lots on internal stuff

   --diagram, -d        Generate diagrams showing modules and 

classes.
You need dot V1.8.6 or later to use the
–diagram
option correctly. Dot is available from
http://www.research.att.com/sw/tools/graphviz/

   --exclude, -x pattern
                        do not process files or directories matching
                        pattern. Files given explicitly on the 

command
line will never be excluded.

 --extension, -E new=old
                        Treat files ending with .new as if they 

ended
with
.old. Using ‘-E cgi=rb’ will cause xxx.cgi
to be
parsed as a Ruby file

 --fileboxes, -F        classes are put in boxes which represents
                        files, where these classes reside. Classes
                        shared between more than one file are
                        shown with list of files that sharing them.
                        Silently discarded if --diagram is not given
                        Experimental.

–force-update, -U forces to scan all sources even if newer
than
the flag file.

       --fmt, -f format name
                        set the output formatter (see below)

      --help, -h        you're looking at it

–help-output, -O explain the various output options

–image-format, -I gif/png/jpg/jpeg
Sets output image format for diagrams. Can
be png, gif, jpeg, jpg. If this option is
omitted, png is used. Requires --diagram.

   --include, -i dir[,dir...]
                        set (or add to) the list of directories
                        to be searched when satisfying :include:
                        requests. Can be used more than once.

–inline-source, -S Show method source code inline, rather
than via a popup link

–line-numbers, -N Include line numbers in the source code

      --main, -m name   'name' will be the initial page displayed

     --merge, -M        when creating ri output, merge processed 

classes
into previously documented classes of the
name
name

  --one-file, -1        put all the output into a single file

        --op, -o dir    set the output directory

    --opname, -n name   Set the 'name' of the output. Has no
                        effect for HTML.

–promiscuous, -p When documenting a file that contains a
module
or class also defined in other files, show
all stuff for that module/class in each
files
page. By default, only show stuff defined in
that particular file.

     --quiet, -q        don't show progress as we parse

        --ri, -r        generate output for use by 'ri.' The files 

are
stored in the ‘.rdoc’ directory under your
home
directory unless overridden by a subsequent
–op parameter, so no special privileges are
needed.

   --ri-site, -R        generate output for use by 'ri.' The files 

are
stored in a site-wide directory, making them
accessible
to others, so special privileges are needed.

 --ri-system, -Y        generate output for use by 'ri.' The files 

are
stored in a system-level directory, making
them
accessible
to others, so special privileges are needed.
This option
is intended to be used during Ruby
installations

 --show-hash, -H        A name of the form #name in a comment
                        is a possible hyperlink to an instance
                        method name. When displayed, the '#' is
                        removed unless this option is specified

     --style, -s stylesheet url
                        specifies the URL of a separate stylesheet.

 --tab-width, -w n      Set the width of tab characters (default 8)

  --template, -T template name
                        Set the template used when generating output

     --title, -t text   Set 'txt' as the title for the output

   --version, -v        display  RDoc's version

    --webcvs, -W url    Specify a URL for linking to a web frontend
                        to CVS. If the URL contains a '%s', the
                        name of the current file will be 

substituted;
if the URL doesn’t contain a ‘%s’, the
filename will be appended to it.

Available output formatters: chm, html, ri, xml

For information on where the output goes, use

rdoc --help-output


Rick DeNatale

Blog: http://talklikeaduck.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
WWR: http://www.workingwithrails.com/person/9021-rick-denatale
LinkedIn: http://www.linkedin.com/in/rickdenatale


#15

Rick Denatale wrote:

And there are lots of options which affect what it outputs

Rick than you very much for all the options :slight_smile:

Hyperlinks to the web starting http:, mailto:, ftp:, or www. are
recognized. An HTTP url that references an external image file is
converted into an inline <IMG…>. Hyperlinks starting ‘link:’ are
assumed to refer to local files whose path is relative to the
–op directory.

Unfortunately, none of the above hyperlinks work for in-line images.
There may very well be a number of directives that work with images and
are not documented for general public. For instance the rdoc’s own
documentation uses the following cool area-clickable image
http://rdoc.sourceforge.net/doc/dot/f_1.png. You can check it out at
http://rdoc.sourceforge.net/doc/index.html. I’d be very happy if someone
would document how this works, but my gut filling is that even their own
documentation may be manually tweaked behind the scene.

I sincerely hope I am wrong, and that someone will show up here and give
us a usable example or at least the damn directive to include a passive
in-line images, rather than a man pages in the style of RtFM.


#16

There may very well be a number of directives that work with images and
are not documented for general public. For instance the rdoc’s own
documentation uses the following cool area-clickable imagehttp://rdoc.sourceforge.net/doc/dot/f_1.png.

I think the reason for why Rick included the output of rdoc --help was
that there is a -D command line option that includes these diagrams.

rather than a man pages in the style of RtFM.

That’s what documentation tools like rdoc & man are made for: being
read.


#17

Tom L. wrote:

That’s what documentation tools like rdoc & man are made
for: being read.

It is rather ironic and perhaps insulting that you would think the
knowledge which is the basis for this discussion comes naturally by
birth.

… the output of rdoc --help was that there is a -D command
line option that includes these diagrams.

Unfortunately, all these references to the graphics all point to
http://www.research.att.com/sw/tools/graphviz/. The web page is
overwhelming and talks about generating graphic. None of this is really
needed. What is missing in rdoc documentation is a simple directive to
include an in-line image - perhaps something like:
±----------------------------+
| # [IMG:URL] |
| # or |
| # [IMG:file://image.png] |
±----------------------------+
Indeed, at one point it would be nice to generate area-clickable image
(diagram) that could be used in rdoc output. But without being able to
place in an inactive - still image, all the reading of tones of
theoretical possibilities, that at the end may not even do what one
wishes, is an unnecessary waste of time. The “smart” or more to the
point annoying answers like yours, Tom, certainly do not help. I already
forgot all the stuff I read and tried when I needed this feature in
rdoc, so much so that I decided to include the missing rdoc feature
myself.

The bottom line is that as a user having a long and considerable
experience with rdoc I still can not put a diagram into my documentation
produced with rdoc, without the additional under the hood meddling, and
forgive me if I find comments like yours rather inappropriate.


#18

On Sat, Feb 21, 2009 at 1:21 AM, Igor P. removed_email_address@domain.invalid
wrote:

documentation uses the following cool area-clickable image
http://rdoc.sourceforge.net/doc/dot/f_1.png. You can check it out at
http://rdoc.sourceforge.net/doc/index.html. I’d be very happy if someone
would document how this works, but my gut filling is that even their own
documentation may be manually tweaked behind the scene.

I’m pretty sure that those are there simply through the use of the
–diagram
option of rdoc and were automatically generated using doc.

For static images all you need to do is put them somewhere relative to
the
docs directory and use the image: markup

For example if I have an image dontswing.jpg in the parent directory of
rdoc
generated doc directory I can do

This documents the Foo class

link:…/dontswing.jpg

class Foo
end

and $rdoc *.rb

shows that image in the documentation for foo.

If you want to put the image somewhere underneath the doc directory, you
can, but you have to do it yourself, and probably want a rake task to do
that after you’ve (re)generated the rdoc output.

I sincerely hope I am wrong, and that someone will show up here and give
us a usable example or at least the damn directive to include a passive
in-line images, rather than a man pages in the style of RtFM.

I’d never done that myself but it really did take just a bit of reading
the
doc and a little experimentation.


Rick DeNatale

Blog: http://talklikeaduck.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
WWR: http://www.workingwithrails.com/person/9021-rick-denatale
LinkedIn: http://www.linkedin.com/in/rickdenatale


#19

Fantastic, Rick “link:file” does work. I also found it in the
documentation. Thank you very much for your help. Sometimes, there just
isn’t enough time to read everything.

Thank you again
Igor


#20

On Feb 19, 2009, at 15:41, Igor P. wrote:

“doc” directory in the same directory where you placed 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 .……