rdoc included in standard distribution?

[Chad Fowler]

I've seen various plans for this dating back more than a year. Is it
still planned?

We would like to introduce an rdoc dependency in RubyGems but are hesitant
if it's not a part of the standard distribution.

Aside from that, it's just a great tool. And the standard library is
being documented in a compatible format.

Anyone have the definitive answer?

Thanks,
Chad

 

[Gavin Sinclair]

I've seen various plans for this dating back more than a year. Is it
still planned?

We would like to introduce an rdoc dependency in RubyGems but are hesitant
if it's not a part of the standard distribution.

Aside from that, it's just a great tool. And the standard library is
being documented in a compatible format.

Anyone have the definitive answer?

Not me, obviously, but you can try to run rdoc in RubyGems, and if it
fails, print a polite message to the user. It's clearly a non-core
dependency.

Anyway, I'd like to see it distributed.

Gavin

 

[Yukihiro Matsumoto]

Hi,

In message "rdoc included in standard distribution?"

|I've seen various plans for this dating back more than a year. Is it
|still planned?

I have said OK. I believe now it's upto Dave Thomas.

matz.

 

[Dave Thomas]

In message "rdoc included in standard distribution?"

|I've seen various plans for this dating back more than a year. Is it
|still planned?

I have said OK. I believe now it's upto Dave Thomas.

What do I need to do? RDoc hasn't changed substantially in a while, and
unless there are problems folks aren't posting to SourceForge, I
believe it's as ready as it will ever be

Cheers


Dave

 

[Yukihiro Matsumoto]

Hi,

In message "Re: rdoc included in standard distribution?"

|What do I need to do? RDoc hasn't changed substantially in a while, and
|unless there are problems folks aren't posting to SourceForge, I
|believe it's as ready as it will ever be

Commit the required library to /lib and rdoc itself to /bin.
I believe you have CVS commit account.

matz.

 

[gabriele renzi]

What do I need to do? RDoc hasn't changed substantially in a while, and
unless there are problems folks aren't posting to SourceForge, I
believe it's as ready as it will ever be

btw, is rdoc ready to produce stuff for ri (and ri is ready to get it)
atm ?
It seem to me someone told me this is possible with newer versions..

 

[Dave Thomas]

btw, is rdoc ready to produce stuff for ri (and ri is ready to get it)
atm ?
It seem to me someone told me this is possible with newer versions..

No, because I wanted to have the ability to be able to add
documentation incrementally (that is, to start off with one set of
modules, and then add others over time), with everything knitting
together nicely. If I do this, I want to do it properly (so that, for
example, root can install the main Ruby docs, and then individual users
can add their own docs as non-root, and from their perspective the
stuff they added would hyperlink correctly to the system wide
documentation).

In the meantime, there's a neat hack over on ruby-doc that takes RDoc
output and converts it to RI format.

Cheers


Dave

 

[Gavin Sinclair]

Hi,

In message "Re: rdoc included in standard distribution?"
on 03/11/30, Dave Thomas <[email protected]> writes:

|What do I need to do? RDoc hasn't changed substantially in a while, and
|unless there are problems folks aren't posting to SourceForge, I
|believe it's as ready as it will ever be

Commit the required library to /lib and rdoc itself to /bin.
I believe you have CVS commit account.

While I want to see rdoc in the standard library, I find it strange
that it should occupy space in the lib directory. Unless I'm
mistaken, it's not really a library; rather an application.

Still, I guess my perception could change. One day we'll see people
doing this:

require 'rdoc'

rdoc = RDoc.new(template, title, ....)
rdoc.generate(*files)

instead of

command = "rdoc -T #{template} --title #{title} ..."]
system command

Hmmm. I like it already.

Gavin

 

[Richard Kilmer]

While I want to see rdoc in the standard library, I find it strange
that it should occupy space in the lib directory. Unless I'm
mistaken, it's not really a library; rather an application.

It is a library...rdoc is just a command line interface to the library

Still, I guess my perception could change. One day we'll see people
doing this:

require 'rdoc'

rdoc = RDoc.new(template, title, ....)
rdoc.generate(*files)

I just added this to RubyGems:

require 'rdoc/rdoc'

rdoc_dir = File.join(@doc_dir, "rdoc")
source_dirs = @spec.require_paths.collect do |req|
File.join(@spec.installation_path, @spec.full_name, req)
end

r = RDoc::RDoc.new
r.document(['--op', rdoc_dir, '--template', 'kilmer'] + source_dirs)

One of the cool things (of many cool things) Dave did in RDoc is make
the #document method accept the ARGV array (or a manually constructed
array like above) which makes using it from Ruby very simple.

-rich

instead of

command = "rdoc -T #{template} --title #{title} ..."]
system command

Hmmm. I like it already.

Gavin

 

[Dave Thomas]

Still, I guess my perception could change. One day we'll see people
doing this:

require 'rdoc'

rdoc = RDoc.new(template, title, ....)
rdoc.generate(*files)

Gavin:

The actual sequence of calls is

require 'rdoc/rdoc'

rdoc = RDoc::RDoc.new
rdoc.document(args)

And you can now do this in the CVS version of Ruby.

Cheers


Dave

 

[Gavin Sinclair]

Gavin:

The actual sequence of calls is

require 'rdoc/rdoc'

rdoc = RDoc::RDoc.new
rdoc.document(args)

Do you see any sense in allowing this?

rdoc = RDoc::RDoc.new do |r|
r.template = 'css2'
r.title = 'FooBar API'
r.main = "README"
r.output_dir = "/tmp/html"
...
end

Perhaps in combination with the argument-passing ability. This means
of initialising data-heavy objects is great, I find. Better than
keyword arguments, because you can look up the attributes in the RDoc
output.

And you can now do this in the CVS version of Ruby.

Cool. What does this mean for rdoc.sourceforge.net?

Gavin

 

[Dave Thomas]

Do you see any sense in allowing this?

I don't know about sense. I've just never felt the need.

Cool. What does this mean for rdoc.sourceforge.net?

It'll die eventually. For now, I'm keeping both up to date.


Cheers


Dave

 

[Chris Thomas]

require 'rdoc/rdoc'

rdoc = RDoc::RDoc.new
rdoc.document(args)

And you can now do this in the CVS version of Ruby.

Super cool. But I ran into one thing right away:

% rdoc --help
/usr/local/lib/ruby/1.8/rdoc/diagram.rb:7:in `require': No such file to
load -- dot/dot (LoadError)
from /usr/local/lib/ruby/1.8/rdoc/diagram.rb:7
from /usr/local/lib/ruby/1.8/rdoc/rdoc.rb:22:in `require'
from /usr/local/lib/ruby/1.8/rdoc/rdoc.rb:22
from /usr/local/bin/rdoc:59:in `require'
from /usr/local/bin/rdoc:59

Could that dependency be conditionalized, as in the following patch?

Index: lib/rdoc/rdoc.rb
===================================================================
RCS file: /src/ruby/lib/rdoc/rdoc.rb,v
retrieving revision 1.1
diff -u -c -3 -r1.1 rdoc.rb
cvs server: conflicting specifications of output style
*** lib/rdoc/rdoc.rb 1 Dec 2003 07:12:48 -0000 1.1
--- lib/rdoc/rdoc.rb 3 Dec 2003 00:32:52 -0000
***************
*** 19,26 ****
require 'rdoc/parsers/parse_simple.rb'
require 'rdoc/options'

- require 'rdoc/diagram'
-
require 'find'
require 'ftools'

--- 19,24 ----
***************
*** 206,212 ****
end

begin
! Diagram.new(file_info, options).draw if options.diagram
gen.generate(file_info)
ensure
Dir.chdir(pwd)
--- 204,213 ----
end

begin
! if options.diagram
! require 'rdoc/diagram'
! Diagram.new(file_info, options).draw
! end
gen.generate(file_info)
ensure
Dir.chdir(pwd)

Thanks,
Chris (no relation

 

[Dave Thomas]

Super cool. But I ran into one thing right away:

% rdoc --help
/usr/local/lib/ruby/1.8/rdoc/diagram.rb:7:in `require': No such file
to load -- dot/

Chris:

Thanks for the patch, but in fact the problem was a missing file in the
commit. When I added rdoc to the standard library, I moved stuff around
to reduce namespace pollution, and I forgot the dot.rb file.

Sorry about that


Dave