[ANN] rdoc 2.1.0 Released

E

Eric Hodel

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/>
 
M

Marcin Raczkowski

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 :)
 
M

Marcin Raczkowski

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,
Click to expand...
--main=NAME \n for example -m README\n"
exit(1)
end
Click to expand...


this fixes frameless template.

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

Eric Hodel

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 :)
Click to expand...

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

Marcin Raczkowski

Eric said:
Yeah, I didn't finish frameless, since it got hard/boring and I didn't
want to sit on other good stuff.
Click to expand...
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
 
J

Joel VanderWerf

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

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

Jeremy McAnally

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

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....
Click to expand...



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

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

Eric Hodel

Then why release broken?
Click to expand...

Due to the many other improvements. Remember:

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"]
$
Click to expand...

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?
Click to expand...

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.
Click to expand...

Yes, I am going to apply it.
 
E

Eric Hodel

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?
Click to expand...

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

Eric Hodel

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

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

Marcin Raczkowski

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

Chris Lowis

Eek.  My, my.  I may look into beefing that up then, though it looks
I've implemented a handful for RDoc::parser::Ruby, and that's probably  
the easiest place to add more.
Click to expand...

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
 
E

Eric Hodel

I'm glad, i just started hacking, and don't know if i did good job,
and what coding convention to follow ;)
Click to expand...

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?
Click to expand...

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

I promise patches and specs in return ^^
Click to expand...

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

Marcin Raczkowski

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


What formats?
Click to expand...

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).
Click to expand...
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.
 
E

Eric Hodel

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.
Click to expand...

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

Jeremy McAnally

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

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


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.
Click to expand...



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

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

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

Similar Threads

[ANN] rdoc 2.5 Released 7
[ANN] rdoc 3.4 Released 0
[ANN] rdoc 3.5.2 Released 0
[ANN] rdoc 3.5 Released 0
[ANN] rdoc 3.6 Released 4
[ANN] RDoc 3 6
[ANN] rdoc 3.2 Released 0
[ANN] rdoc 3.1 Released 0

Members online

Total: 59 (members: 3, guests: 56)
Robots: 305

Forum statistics

Threads
473,968
Messages
2,570,152
Members
46,697
Latest member
AugustNabo

Latest Threads

Top