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

K

Kenneth McDonald

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
 
K

Kenneth McDonald

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

Thanks,
Ken
 
R

Rick DeNatale

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

On Thu, Feb 19, 2009 at 4:24 PM, Kenneth McDonald <
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.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
WWR: http://www.workingwithrails.com/person/9021-rick-denatale
LinkedIn: http://www.linkedin.com/in/rickdenatale
 
J

Joel VanderWerf

Rick said:
On Thu, Feb 19, 2009 at 4:24 PM, Kenneth McDonald <

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
 
I

Igor Pirnovar

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

Tom Cloyd

Igor said:
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
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
J

Joel VanderWerf

Igor said:
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.
 
J

James Britt

Igor said:
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.

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

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

Tom Link

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

Tom Link

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

Igor Pirnovar

James said:
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 said:
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 ;)
 
J

James Britt

Igor said:
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.


@facepalm = true



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

Rick DeNatale

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

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 ;)


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
 
I

Igor Pirnovar

Rick said:
And there are lots of options which affect what it outputs

Rick than you very much for all the options :)
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.
 
T

Tom Link

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

Igor Pirnovar

Tom said:
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.
 
R

Rick DeNatale

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

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'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
 
I

Igor Pirnovar

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
 
E

Eric Hodel

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

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,482
Members
44,900
Latest member
Nell636132

Latest Threads

Top