RDoc question

thomthom

Trying out Allison - as it was frameless and had a nice quick filter feature. But I get errors trying to build the docs.


C;\Program Files (x86)\Google\Google SketchUp 7\Plugins\TT_Lib>allison *.rb --main README.txt --debu
g
--inline-source will be removed from RDoc on or after August 2009
Parsing sources with 2 thread(s)...
100% [14/14]  window.rb

Generating Darkfish...
could not find template "C;/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison"
C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;111;in `initialize'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `new'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `for'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/rdoc.rb;314;in `document'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/bin/rdoc;15
        C;/Ruby/bin/rdoc;19;in `load'
        C;/Ruby/bin/rdoc;19


C;\Program Files (x86)\Google\Google SketchUp 7\Plugins\TT_Lib>

In that folder there is:
allison.css allison.js allison.rb

thomthom

allison --path returns C:/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison
Seem to be missing .rb

So I tried rdoc *.rb --main README.txt --debug --template "C:/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison.rb"

but that resulted in

C;\Program Files (x86)\Google\Google SketchUp 7\Plugins\TT_Lib>rdoc *.rb --main README.txt --debug -
-template "C;/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison.rb"
Parsing sources with 2 thread(s)...
100% [14/14]  window.rb

Generating Darkfish...
could not find template "C;/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison.rb"
C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;111;in `initialize'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `new'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `for'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/rdoc.rb;314;in `document'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/bin/rdoc;15
        C;/Ruby/bin/rdoc;19;in `load'
        C;/Ruby/bin/rdoc;19

I have no idea why. incompatible RDoc version?

thomthom

I installed Ruby on a secondary machine. I got the allison to work now. Seem that my ruby installation is a wee bit screwed up.

But the original rdoc does not support formatting for bold -italic- and underlined etc. and call-seq also isn't recognised.

thomthom

and updating rdoc causes the same loss of pragraphs etc... and still missing directive. and it broke the allison template.

ok. I think I might have to settle for original Rdoc, and use allison with less formatting options. but still wish the directives would work...

thomthom

makes so sense that I'm missing the formatting with the RDoc that comes with ruby. http://ruby-doc.org/core/ <- should be supported.

gaah. why is this not an easy operation?

thomthom

Found a solution: bye bye RDoc! Hello Yard!

YARD - A Ruby Documentation Tool

YARD is an extensible Ruby Documentation Tool (Yay!) for consistent documentation.

(yardoc.org)

Dan Rathbun

@unknownuser said:

Markup

The markup engine looks for a document’s natural left margin. This is used as the initial margin for the document.* Consecutive lines starting at this margin are considered to be a paragraph.

Does RDoc recognize \n ?

As in:
` # Returns an Array object.

\n

Added: 1.1.0

def to_a(orient_by_columns = false)`

or would that just produce "*n" ?

I think I have seen some markup in the standard ruby lib files that had <p></p> embedded.
_

thomthom

The missing paragraphs in Darkfish might just be due to it's CSS style. With the original RDoc they where there.

But it would not recognize various directives, couldn't find my README file.
The original seemed bugged, as in when you rebuilt it'd rebuild just the changed files, but you'd lose the existing in your index.
The exeprience is that it's abig mess.

While YARD just worked. Based on RDoc syntax, but with @tags.

Dan Rathbun

@thomthom said:

While YARD just worked. Based on RDoc syntax, but with @tags.

I'll have to bookmark that then. maybe it should go on the Sticky Links page?

thomthom

Maybe. Could be worth to test it first? I've only looked briefly on it, but over the weekend I hope to get time to document my TT_Lib library with it. Then I can say if I recommend it.
But I do like the sound of the @tags it has available. Appear to leave more control than plain RDoc. Such as parameter types and return types and version numbering.

Dan Rathbun

@thomthom said:

But I do like the sound of the @tags it has available. Appear to leave more control than plain RDoc. Such as parameter types and return types and version numbering.

It's sounding better all the time!

Keep us advised.