[ANN] rdoc 2.1.0 Released

ruby-talk
1

rdoc version 2.1.0 has been released!

* <http://rubyforge.org/projects/rdoc/>

RDoc is an application that produces documentation for one or more Ruby source
files. RDoc includes the `rdoc` and `ri` tools for generating and displaying
online documentation.

At this point in time, RDoc 2.x is a work in progress and may incur further
API changes beyond what has been made to the RDoc 1.0.1. Command-line tools
are largely unaffected, but internal APIs may shift rapidly.

Changes:

== 2.1.0 / 2008-07-20

* 3 Major Enhancements:
  * RDoc now knows about meta-programmed methods, see RDoc::Parser::Ruby
  * Reorganized parsers under RDoc::Parser base class
  * ri now walks the ancestors of a class looking for a method e.g. ri
    File#read displays documentation for IO#read (may require regeneration of
    ri data)
* 5 Minor Enhancements:
  * Allow links to files
  * Default options now taken from RDOCOPT environment variable
  * Class method documentation can be found at toplevel now (def X.foo)
  * Allow HTML templates distributed as gems to be loaded with the -T option,
    just like the standard templates in rdoc/generator/html (so an HTML
    template lib/new_template.rb in a gem can be used with rdoc -T new_template)
  * `rdoc -v` prints out files, classes, modules and methods as it goes
* 11 Bug Fixes:
  * `ri Foo.bar` now looks for class methods also
  * Sections work in the default template again
  * Doesn't warn about :foo:: list item being an unrecognized directive
  * RDoc no longer converts characters inside tt tags
  * Fixed "unitialized constant RDoc::Markup::ToHtml::HTML"
  * Fixed generation of relative links
  * Fixed various diagram generation issues
  * Fixed templates broken by switch to erb
  * Fixed issue with <!-- --> style comments
  * Lowercase words are no longer rdoc'd as methods without leading #, as
    described in the documentation
  * RDoc now correctly sets superclasses if they were originally unknown

* <http://rubyforge.org/projects/rdoc/>

2

Eric Hodel wrote:

rdoc version 2.1.0 has been released!

...

* Fixed generation of relative links

Thanks!

The other enhancements look great too.

···

--
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

3

Fix for frameless generation

looks like there was accessor for mine_page and now it's gone, that's bug number 1

bug number 2 is failing to provide fallback if someone didn't provide main file for frameless file.
main stays nil, and it's not checked (there's only check if it responds for one method, and if not other method is called)

diff -r rdoc-2.1.0/lib/rdoc/generator/html.rb rdoc-2.1.0-mine-working/lib/rdoc/generator/html.rb
239c239
< main_page == klass.context.full_name

···

---
> @main_page == klass.context.full_name
241a242,253
>
> if main.nil?
> @main_page = "README"
> main = @files.find do |file|
> @main_page == file.name
> end
> end
>
> unless main
> puts "you heve to specify main page with -m, --main=NAME \n for example -m README\n"
> exit(1)
> end

this fixes frameless template.

I really think you should at least check every template you provide with default options before releasing it!

4

I started playing with new release and frameless template doesn't work.

simply adding FRAMELESS = trye to main html template causes following error:

var/lib/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/generator/html.rb:239:in `gen_main_index': undefined local variable or method `main_page' for #<RDoc::Generator::HTML:0xb78c7dac> (NameError)
         from /usr/lib/ruby/1.8/erb.rb:740:in `find'
         from /var/lib/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/generator/html.rb:238:in `each'
         from /var/lib/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/generator/html.rb:238:in `find'
         from /var/lib/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/generator/html.rb:238:in `gen_main_index'
         from /var/lib/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/generator/html.rb:165:in `generate_html'
         from /var/lib/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/generator/html.rb:87:in `generate'
         from /var/lib/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/rdoc.rb:278:in `document'
         from /var/lib/gems/1.8/gems/rdoc-2.1.0/bin/rdoc:15
         from /usr/bin/rdoc:19:in `load'
         from /usr/bin/rdoc:19

I'm trying to find a source of the problem, but i'm not sure if i'll be able to.

otherwise great job :slight_smile:

5

Yeah, I didn't finish frameless, since it got hard/boring and I didn't want to sit on other good stuff.

···

On Jul 21, 2008, at 14:05 PM, Marcin Raczkowski wrote:

I started playing with new release and frameless template doesn't work.

simply adding FRAMELESS = trye to main html template causes following error:

I'm trying to find a source of the problem, but i'm not sure if i'll be able to.

otherwise great job :slight_smile:

6

Eric Hodel wrote:

I started playing with new release and frameless template doesn't work.

simply adding FRAMELESS = trye to main html template causes following error:

I'm trying to find a source of the problem, but i'm not sure if i'll be able to.

otherwise great job :slight_smile:

Yeah, I didn't finish frameless, since it got hard/boring and I didn't want to sit on other good stuff.

Then why release broken?
And why didn't you at least add it to notes that this feature is broken and if you have frameless template don't install it?

anyway i sent patch that fixes frameless, took me around 30 mins, it uses "README" as default and if it isn't find provides helpfull info.

I hope you find it usefull.

greets

···

On Jul 21, 2008, at 14:05 PM, Marcin Raczkowski wrote:

7

He already answered why: "I didn't want to sit on other good stuff". Besides, all software ships broken.

···

On Jul 22, 2008, at 02:56 , Marcin Raczkowski wrote:

Eric Hodel wrote:

Yeah, I didn't finish frameless, since it got hard/boring and I didn't want to sit on other good stuff.

Then why release broken?

8

Eric Hodel wrote:

I started playing with new release and frameless template doesn't work.

simply adding FRAMELESS = trye to main html template causes following error:

I'm trying to find a source of the problem, but i'm not sure if i'll be able to.

otherwise great job :slight_smile:

Yeah, I didn't finish frameless, since it got hard/boring and I didn't want to sit on other good stuff.

Then why release broken?

Due to the many other improvements. Remember:

At this point in time, RDoc 2.x is a work in progress and may incur further
API changes beyond what has been made to the RDoc 1.0.1. Command-line tools
are largely unaffected, but internal APIs may shift rapidly.

RDoc contains many pieces that interact in a tightly coupled manner. Making changes in one area usually leads to some breakages in another area. There are also almost no tests for RDoc, so I made some sacrifices for a net improvement. For example:

$ ri Hash#map
--------------------------------------------------------- Enumerable#map
     enum.collect {| obj | block } => array
     enum.map {| obj | block } => array
------------------------------------------------------------------------
     Returns a new array with the results of running block once for
     every element in enum.

        (1..4).collect {|i| i*i } #=> [1, 4, 9, 16]
        (1..4).collect { "cat" } #=> ["cat", "cat", "cat", "cat"]
$

I think this is a rather wonderful feature, and people will care more about it than about broken templates.

If you don't like the things I've broken (and will continue to break) while I develop RDoc 2.x into a fine-tuned machine, you can stay with RDoc 1.0.1 that is bundled with ruby 1.8.

(In fact, I broke the templates in RDoc 2.0. They're mostly fixed now.)

And why didn't you at least add it to notes that this feature is broken and if you have frameless template don't install it?

I can't see where I mentioned it in the release notes at all. Because you have extra curiosity, you found it :slight_smile:

anyway i sent patch that fixes frameless, took me around 30 mins, it uses "README" as default and if it isn't find provides helpfull info.

I hope you find it usefull.

Yes, I am going to apply it.

···

On Jul 22, 2008, at 02:56 AM, Marcin Raczkowski wrote:

On Jul 21, 2008, at 14:05 PM, Marcin Raczkowski wrote:

9

Ryan Davis wrote:

Eric Hodel wrote:

Yeah, I didn't finish frameless, since it got hard/boring and I didn't want to sit on other good stuff.

Then why release broken?

He already answered why: "I didn't want to sit on other good stuff". Besides, all software ships broken.

Not to mention the prev release was broken in one particular aspect (links), and this release fixed it. So from one point of view it is less broken....

···

On Jul 22, 2008, at 02:56 , Marcin Raczkowski wrote:

--
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

10

I'm glad, i just started hacking, and don't know if i did good job, and what coding convention to follow :wink:

anyway I'm going to work some time on RDoc becouse i want it to generate some other formats then what already is implemented, i have question could you put together quick hacking guide?

What lies where, and what's the basic flow of data/calls?

I promise patches and specs in return ^^

11

Uh, then where are the tests? Those seem like two fairly major
features that were broken. I don't know the details, but they don't
seem like edge case usages that were broken either. Is RDoc poorly
covered or something?

Yes, "patches please." I know the response, even though I think it's
completely useless.

--Jeremy

···

On Tue, Jul 22, 2008 at 3:30 PM, Joel VanderWerf <vjoel@path.berkeley.edu> wrote:

Ryan Davis wrote:

On Jul 22, 2008, at 02:56 , Marcin Raczkowski wrote:

Eric Hodel wrote:

Yeah, I didn't finish frameless, since it got hard/boring and I didn't
want to sit on other good stuff.

Then why release broken?

He already answered why: "I didn't want to sit on other good stuff".
Besides, all software ships broken.

Not to mention the prev release was broken in one particular aspect (links),
and this release fixed it. So from one point of view it is less broken....

--
     vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

--
http://jeremymcanally.com/
http://entp.com/

My books:

http://humblelittlerubybook.com/ (FREE!)

12

I made a change, is this suitable?

Index: lib/rdoc/generator/html.rb

···

On Jul 23, 2008, at 02:04 AM, Marcin Raczkowski wrote:

I'm glad, i just started hacking, and don't know if i did good job, and what coding convention to follow :wink:

===================================================================
--- lib/rdoc/generator/html.rb (revision 114)
+++ lib/rdoc/generator/html.rb (working copy)
@@ -256,8 +256,16 @@ class RDoc::Generator::HTML

        if main.nil? then
          main = @classes.find do |klass|
- main_page == klass.context.full_name
+ @main_page == klass.context.full_name
          end
+
+ main = @files.find do |file|
+ file.name =~ /^README/
+ end
+ end
+
+ unless main then
+ raise RDoc::Error, 'main page not found, please specify with --main'
        end
      else
        main = RDoc::TemplatePage.new @template::INDEX

I have README, not README.txt, and some people have README.rdoc, so this should work better for most people.

anyway I'm going to work some time on RDoc becouse i want it to generate some other formats then what already is implemented, i have question could you put together quick hacking guide?

What formats?

What lies where, and what's the basic flow of data/calls?

I promise patches and specs in return ^^

I will try to improve the RDoc documentation of various locations, but here's a quick guide:

RDoc is composed of the following parts: parsing, intermediate documentation representation, generators, markup and ri.

If you're writing a new output format, you're most interested in the intermediate documentation representation and generators, but you may want to build your own generator if you're not doing something roughly similar to HTML (ri has a completely separate thing to spit out its yaml files).

The intermediate representation is split amongst various classes in lib/rdoc/code_objects.rb. How these fit together should be straightforward.

The heart of the generators is RDoc::Generator::build_indicies, which turns the various files, classes and modules found into a second intermediate representation for HTML, etc output. (I'm not sure if this is strictly necessary, I am highly inclined to rip it out and simplify the generators, but that's a big, big job.)

I don't remember how ri does its thing, but part of it is in RDoc::RI::Writer.

13

Other than a few tests for a small subset of RDoc::Markup, there weren't any when I inherited it.

···

On Jul 22, 2008, at 14:09 PM, Jeremy McAnally wrote:

Uh, then where are the tests? Those seem like two fairly major
features that were broken. I don't know the details, but they don't
seem like edge case usages that were broken either. Is RDoc poorly
covered or something?

14

Eric Hodel wrote:

I'm glad, i just started hacking, and don't know if i did good job, and what coding convention to follow :wink:

I made a change, is this suitable?

Sure.

I have README, not README.txt, and some people have README.rdoc, so this should work better for most people.

Yea.

anyway I'm going to work some time on RDoc becouse i want it to generate some other formats then what already is implemented, i have question could you put together quick hacking guide?

What formats?

Hmmm. well I want to generate stubs of Ruby classes in another languages(Python, JS, and more) , It's a part of anothet project, that i hope will see the open source light next week.

I was also thinking about dumping documentation to database for further processing (wiki-like documentation editing online?, mayby links to use cases? etc.)

RDoc is composed of the following parts: parsing, intermediate documentation representation, generators, markup and ri.

If you're writing a new output format, you're most interested in the intermediate documentation representation and generators, but you may want to build your own generator if you're not doing something roughly similar to HTML (ri has a completely separate thing to spit out its yaml files).

From what i noticed, i can generate almost any format using HTML template, but I'll give it a try

I was thinking about using ParseTree + friends for this project, but having a documentation is a big bonus, if I'll have sudden attack of craziness, i'll try to make Rdoc parser spit out something similar to PareseTree's AST but with links to documentation string.

···

On Jul 23, 2008, at 02:04 AM, Marcin Raczkowski wrote:

15

Eek. My, my. I may look into beefing that up then, though it looks
like you've done a fine job already.

--Jeremy

···

On Tue, Jul 22, 2008 at 5:31 PM, Eric Hodel <drbrain@segment7.net> wrote:

On Jul 22, 2008, at 14:09 PM, Jeremy McAnally wrote:

Uh, then where are the tests? Those seem like two fairly major
features that were broken. I don't know the details, but they don't
seem like edge case usages that were broken either. Is RDoc poorly
covered or something?

Other than a few tests for a small subset of RDoc::Markup, there weren't any
when I inherited it.

--
http://jeremymcanally.com/
http://entp.com/

My books:
http://manning.com/mcanally/
http://humblelittlerubybook.com/ (FREE!)

16

In a future version, we'll use ruby_parser to extract documentation, which has a UnifiedRuby-compatible output.

···

On Jul 23, 2008, at 12:33 PM, Marcin Raczkowski wrote:

I was thinking about using ParseTree + friends for this project, but having a documentation is a big bonus, if I'll have sudden attack of craziness, i'll try to make Rdoc parser spit out something similar to PareseTree's AST but with links to documentation string.

17

In the vein of wiki like editing of documentation:
http://www.github.com/iownbey/docbox

(I'm mentoring that project for the Google Summer of Code :))

--Jeremy

···

On Wed, Jul 23, 2008 at 2:33 PM, Marcin Raczkowski <mailing.mr@gmail.com> wrote:

Eric Hodel wrote:

On Jul 23, 2008, at 02:04 AM, Marcin Raczkowski wrote:

I'm glad, i just started hacking, and don't know if i did good job, and
what coding convention to follow :wink:

I made a change, is this suitable?

Sure.

I have README, not README.txt, and some people have README.rdoc, so this
should work better for most people.

Yea.

anyway I'm going to work some time on RDoc becouse i want it to generate
some other formats then what already is implemented, i have question could
you put together quick hacking guide?

What formats?

Hmmm. well I want to generate stubs of Ruby classes in another
languages(Python, JS, and more) , It's a part of anothet project, that i
hope will see the open source light next week.

I was also thinking about dumping documentation to database for further
processing (wiki-like documentation editing online?, mayby links to use
cases? etc.)

RDoc is composed of the following parts: parsing, intermediate
documentation representation, generators, markup and ri.

If you're writing a new output format, you're most interested in the
intermediate documentation representation and generators, but you may want
to build your own generator if you're not doing something roughly similar to
HTML (ri has a completely separate thing to spit out its yaml files).

From what i noticed, i can generate almost any format using HTML template,
but I'll give it a try

I was thinking about using ParseTree + friends for this project, but having
a documentation is a big bonus, if I'll have sudden attack of craziness,
i'll try to make Rdoc parser spit out something similar to PareseTree's AST
but with links to documentation string.

--
http://jeremymcanally.com/
http://entp.com/

My books:
http://manning.com/mcanally/
http://humblelittlerubybook.com/ (FREE!)

18

I've implemented a handful for RDoc::Parser::Ruby, and that's probably the easiest place to add more.

···

On Jul 22, 2008, at 16:04 PM, Jeremy McAnally wrote:

On Tue, Jul 22, 2008 at 5:31 PM, Eric Hodel <drbrain@segment7.net> > wrote:

On Jul 22, 2008, at 14:09 PM, Jeremy McAnally wrote:

Uh, then where are the tests? Those seem like two fairly major
features that were broken. I don't know the details, but they don't
seem like edge case usages that were broken either. Is RDoc poorly
covered or something?

Other than a few tests for a small subset of RDoc::Markup, there weren't any
when I inherited it.

Eek. My, my. I may look into beefing that up then, though it looks
like you've done a fine job already.

19

Jeremy McAnally wrote:

In the vein of wiki like editing of documentation:
http://www.github.com/iownbey/docbox

(I'm mentoring that project for the Google Summer of Code :))

--Jeremy

Yea i heard about it, and I hope you'll succeed :wink: mayby my code will help in that.

20

Eric Hodel wrote:

···

On Jul 23, 2008, at 12:33 PM, Marcin Raczkowski wrote:

I was thinking about using ParseTree + friends for this project, but having a documentation is a big bonus, if I'll have sudden attack of craziness, i'll try to make Rdoc parser spit out something similar to PareseTree's AST but with links to documentation string.

In a future version, we'll use ruby_parser to extract documentation, which has a UnifiedRuby-compatible output.

Did you start any work towards that goal?