Rdoc 2.1.0 Released

miracleofmagick · July 21, 2008, 11:27am

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/

miracleofmagick · July 21, 2008, 6:26pm

Eric H. wrote:

rdoc version 2.1.0 has been released!
…

Fixed generation of relative links

Thanks!

The other enhancements look great too.

miracleofmagick · July 21, 2008, 11:12pm

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 methodmain_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:ineach’
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:ingen_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:ingenerate’
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:inload’
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

miracleofmagick · July 22, 2008, 2:22am

On Jul 21, 2008, at 14:05 PM, Marcin R. 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

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

miracleofmagick · July 21, 2008, 11:34pm

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!

miracleofmagick · July 22, 2008, 8:30pm

On Jul 22, 2008, at 02:56 , Marcin R. wrote:

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

miracleofmagick · July 22, 2008, 10:37pm

Ryan D. wrote:

On Jul 22, 2008, at 02:56 , Marcin R. wrote:

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

miracleofmagick · July 22, 2008, 12:02pm

Eric H. wrote:

otherwise great job

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

miracleofmagick · July 23, 2008, 12:36am

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

otherwise great job
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:

    (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

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.

miracleofmagick · July 22, 2008, 11:17pm

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
[email protected] wrote:

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

miracleofmagick · July 23, 2008, 12:37am

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.

miracleofmagick · July 23, 2008, 1:10am

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 H. [email protected]
wrote:

–
http://jeremymcanally.com/
http://entp.com/

My books:

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

miracleofmagick · July 23, 2008, 1:20am

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

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.

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

miracleofmagick · July 23, 2008, 11:10am

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

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

I’m also slowly getting up to speed with the codebase in the hope of
contributing tests, and improving texinfo generation. Thanks for the
pointer to RDoc::Parser::Ruby as a place to start.

Chris

miracleofmagick · July 23, 2008, 11:13am

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

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

miracleofmagick · July 23, 2008, 8:45pm

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

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

I made a change, is this suitable?

Index: lib/rdoc/generator/html.rb

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

miracleofmagick · July 24, 2008, 12:24am

On Jul 23, 2008, at 12:33 PM, Marcin R. 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.

miracleofmagick · July 23, 2008, 9:39pm

Eric H. wrote:

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

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

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.

miracleofmagick · July 24, 2008, 10:01am

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 mayby my code will
help in that.

miracleofmagick · July 24, 2008, 10:02am

Eric H. wrote:

On Jul 23, 2008, at 12:33 PM, Marcin R. 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?

Rdoc 2.1.0 Released

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

Index: lib/rdoc/generator/html.rb

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