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

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Kenneth McDonald (Guest)
on 2009-02-19 23:30
(Received via mailing list)
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
Kenneth McDonald (Guest)
on 2009-02-19 23:35
(Received via mailing list)
An additional note: adding a .rb suffix to the filename and command
line did not help.

Thanks,
Ken
Rick D. (Guest)
on 2009-02-20 01:11
(Received via mailing list)
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
Joel VanderWerf (Guest)
on 2009-02-20 01:29
(Received via mailing list)
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
Igor P. (Guest)
on 2009-02-20 01:41
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  +------------------------------------------+
Tom C. (Guest)
on 2009-02-20 02:50
(Received via mailing list)
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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Joel VanderWerf (Guest)
on 2009-02-20 02:54
(Received via mailing list)
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.
James B. (Guest)
on 2009-02-20 04:36
(Received via mailing list)
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
Tom L. (Guest)
on 2009-02-20 06:40
(Received via mailing list)
> >   | 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 B. (Guest)
on 2009-02-20 08:40
(Received via mailing list)
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
Tom L. (Guest)
on 2009-02-20 19:48
(Received via mailing list)
> 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.
Igor P. (Guest)
on 2009-02-20 19:50
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 ;)
James B. (Guest)
on 2009-02-20 22:50
(Received via mailing list)
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
Rick D. (Guest)
on 2009-02-21 01:21
(Received via mailing list)
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 ;)


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
Igor P. (Guest)
on 2009-02-21 08:21
Rick Denatale wrote:

> 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.
Tom L. (Guest)
on 2009-02-21 08:33
(Received via mailing list)
> 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.
Igor P. (Guest)
on 2009-02-21 18:19
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.
Rick D. (Guest)
on 2009-02-21 21:40
(Received via mailing list)
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
Igor P. (Guest)
on 2009-02-21 22:48
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
Eric H. (Guest)
on 2009-02-25 19:37
(Received via mailing list)
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 .&#8230;..
Eric H. (Guest)
on 2009-02-25 19:39
(Received via mailing list)
On Feb 19, 2009, at 22:40, James B. wrote:
>
> Thanks.
>
> Do you know if this is supported by the Rdoc gem?

It is, but it must appear in a Ruby file :(
This topic is locked and can not be replied to.