rtomayko / rocco Goto Github PK

If I put Rocco in any gem group that gets loaded with my application (such as dev or none), I get the following error (with newlines inserted for readability):

/Users/me/.rvm/gems/ree-1.8.7-2011.03/gems/
  activerecord-2.3.10/lib/active_record/associations/
  association_proxy.rb:146:
  in `exists?': wrong number of arguments (0 for 1) (ArgumentError)

I can solve the issue by moving Rocco to a different gem group:

# in Gemfile:
group :docs do
  gem 'rocco', '~> 0.6.0'
end

Rocco files don't get displayed correctly at the moment because the location of the stylesheet changed and moved to http://jashkenas.github.com/docco/resources/linear/docco.css. Why don't you keep a copy of this in your project so you aren't dependent on what happens in docco.

Rocco assumes that all files processed in one run are written in the same language. It'd be nice if we would default to letting pygmentize figure it out (based on filename), and use the language CLI option as an override rather than a requirement.

This involves running pygmentize without a specified language, checking the error code, and when an error pops up, running pygmentize again with the language inline.

I'm trying to use rocco for haskell, but the resulting page is just blank.

Here's my simple file:

-- foo
main = putStrLn "bar"

when running rocco and specifying "--" as the comment chars, all I get is a blank page (with myfile.hs at the top). If I don't specify the comments, and replace "--" with "#" in the source code, it works fine.

One of the best features in redcarpet is the codeblock syntax (AKA Fenced Code) which allows for

class This
  # ...

But Rocco doesn't have it set automatically! Since this setting is one of those "Doesn't do anything if you dont use it, does great stuff if you do" configurations I bet it would be cooler if it was automatically on.

on line 213 :
{'lang' => @options['language'], 'code' => code}

shuld be

{'lang' => @options[:language], 'code' => code}

I hate to throw that term out there, but this project seems to have over 20 open pulls, and some 15 issues beyond.

Has the maintainer simply become too busy to work on this? It's always disheartening installing a recommended tool, seeing it fail, and then seeing "under the hood" and seeing the rust.

We should pull the CSS into this repo, and just embed it into the templates (with a flag, perhaps?)

It'd be nice if you could integrate the changes from http://github.com/jashkenas/docco/commit/f8a88d66b381a1c04358fa9ef31dd58871b22dd6 into Rocco. Right now, #s are lying around everywhere, as they changed form in Docco. :)

Works fine on other rubies (I've tried 1.9.3), but I have this problem on 1.9.2-p136

Michael$ gem install rocco
    Fetching: mustache-0.99.1.gem (100%)
    Fetching: rocco-0.5.gem (100%)
    Successfully installed mustache-0.99.1
    Successfully installed rocco-0.5
    2 gems installed
    Installing ri documentation for mustache-0.99.1...
    Installing ri documentation for rocco-0.5...
    Installing RDoc documentation for mustache-0.99.1...
    Installing RDoc documentation for rocco-0.5...

Michael$ rocco -o doc lib/*.rb
    rocco: lib/umlify.rb -> doc/lib/umlify.html
    /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/mustache-0.99.1/lib/mustache/settings.rb:142:in `read': No such file or directory -         /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/rocco-0.5/lib/rocco/rocco/layout.mustache (Errno::ENOENT)
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/mustache-0.99.1/lib/mustache/settings.rb:142:in `template'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/mustache-0.99.1/lib/mustache/settings.rb:157:in `template'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/mustache-0.99.1/lib/mustache.rb:108:in `render'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/rocco-0.5/lib/rocco.rb:108:in `to_html'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/rocco-0.5/bin/rocco:94:in `block (2 levels) in <top (required)>'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/rocco-0.5/bin/rocco:94:in `open'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/rocco-0.5/bin/rocco:94:in `block in <top (required)>'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/rocco-0.5/bin/rocco:89:in `each'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/gems/rocco-0.5/bin/rocco:89:in `<top (required)>'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/bin/rocco:19:in `load'
from /Users/Michael/.rvm/gems/ruby-1.9.2-p136@umlify/bin/rocco:19:in `<main>'

Just as the summary says, trying to run rocco --help results in a nice backtrace:

/usr/lib/ruby/gems/1.9.1/gems/rocco-0.4/bin/rocco:17:in `usage': undefined method `grep' for #<String:0x000000029b2e40> (NoMethodError)
from /usr/lib/ruby/gems/1.9.1/gems/rocco-0.4/bin/rocco:40:in `block (2 levels) in <top required)>'
from /usr/lib/ruby/1.9.1/optparse.rb:1271:in `call'
from /usr/lib/ruby/1.9.1/optparse.rb:1271:in `block in parse_in_order'
from /usr/lib/ruby/1.9.1/optparse.rb:1258:in `catch'
from /usr/lib/ruby/1.9.1/optparse.rb:1258:in `parse_in_order'
from /usr/lib/ruby/1.9.1/optparse.rb:1252:in `order!'
from /usr/lib/ruby/1.9.1/optparse.rb:1343:in `permute!'
from /usr/lib/ruby/1.9.1/optparse.rb:1364:in `parse!'
from /usr/lib/ruby/gems/1.9.1/gems/rocco-0.4/bin/rocco:41:in `block in <top (required)>'
from /usr/lib/ruby/1.9.1/optparse.rb:1738:in `options'
from /usr/lib/ruby/gems/1.9.1/gems/rocco-0.4/bin/rocco:35:in `<top (required)>'
from /usr/bin/rocco:19:in `load'
from /usr/bin/rocco:19:in `<main>'                                                                    

Version: ruby 1.9.1p378 (2010-01-10 revision 26273) [x86_64-linux]

just for fun, probably not worth merging in given diff --stat vs value

http://github.com/sr/rocco/compare/master...webservice
http://github.com/sr/roko
http://roko.heroku.com/rtomayko/rocco/lib/rocco.rb

I'm sure I ought to be using shocco for bash code (ha!), but since the fix is trivial, I'd appreciate it if you could pull it in. Pull request coming shortly.

PEP 263 specifies a mechanism for signifying a python script's encoding. For the same reasons that we skip shebangs, we should skip these.

Having an actual rake task file that can be installed in lib/tasks for rails applications would make implementing this into a rails application far simpler. Since you already have some comments on this in the source code this would probably not be that difficult to implement.

Steps to reproduce:

Go to a Rails project in the Terminal

Type

rocco app/**/*.rb --output=doc

Result

The generated table of contents lists all the controllers, helpers, and models but links only to the filename. Thus, most of the links in the table don't go to any page.

Expected

Links in the TOC should include the relative path to the original file for which the documentation was generated.

Was surprised that this was the case. Is this just not done yet, or is there a specific reason why multiline comments aren't supported?

Hi

Rocco 0.4 messes things up: documentation is moved to the end, # DIVIDER
are not removed.

The gist demonstrates that.

Regards

--Włodek Bzyl

Great tool! Thanks.

At the moment there's a # symbol before each comment in the output (see e.g. http://rtomayko.github.com/rocco/). I don't think that's what you want, is it?

When running the unit tests with Redcarpet 2 installed (using redcarpet/compat to get a backwards compatible API), I get the following error:

  1) Failure:
test_highlighted_in_blocks(RoccoDocblockAnnotationsTest) [/Users/lambda/src/rocco/test/test_docblock_annotations.rb:18]:
<"<p>Comment</p>\n\n<blockquote><p><strong>param</strong> type name</p></blockquote>\n"> expected but was
<"<p>Comment\n&gt; <strong>param</strong> type name  </p>\n">.

This is due to there not being a blank line inserted between the paragraph and the blockquote, so Redcarpet just parses it as all part of one big paragraph.

This test works if I use RDiscount instead of Redcarpet.

I am wondering about the value of trying to support three different Markdown processors at once. Redcarpet changed their API entirely, though supplying a limited backwards-compatible API, and is more strict about separating blocks with blank lines. Bluecloth does not not support the :smart option which is passed into Markdown.new (and throws an error for unknown options, so it fails to work entirely), and Redcarpet's backwards-compatible API ignores any options passed. Is it really important to support three different incompatible Markdown processors, or would it make sense to just switch to one, probably RDiscount as it seems to work best in Rocco?

When writing XML comments that span multiple paragraphs and/or are hardwrapped, preceding spaces or tabs will sometimes produce unintended Markdown code blocks.

IMHO, rocco should look at what character (space or tab) and how many precede of them precede the comment mark <!--, and ignore that same preceding string in subsequent lines of a multiparagraph multiline comment.

You can test with this sample code, although note that tabs or spaces for nesting also produces different output (which should not IMHO):

<?xml version="1.0" encoding="UTF-8"?>

<!-- 
This is a test of a non indented multiparagraph comment.

Two paragraphs but still renders fine
 -->
<bar/>

<!-- This is another test.

Two paragraphs but still renders fine -->
<foo>

    <!-- 
    (1) Yet start indenting things…

    and code is not rendered as expected.
     -->
    <bar/>

    <!-- (2) Yet start indenting things…

    and code is not rendered as expected. -->
    <bar/>

    <!-- (3) Yet start indenting things…

    and code is not rendered as
    expected. -->
    <bar/>
</foo>

See: http://github.com/quackingduck/rocco/commit/e207dc0cde47f532f87e27b09b324d247da807bf

Is there anything planned for arbitrary languages and comment characters to be passed to Rocco, or will it stay Ruby-centric? I could see myself documenting a lot of things I write in this, regardless of language.

Hey, I recently had to run rocco against some HTML files to generate documentation from the Markup in them.

I used:

rocco *.html

To my surprise, rocco replaced all of the HTML files I wanted to document with the documentation generated.

In hindsight, I should have predicted that this would happen, since rocco replaces the input file extension with html and overwrites the existing content. Luckily, I had everything backed up, so this wasn't an issue.

I would like to suggest that rocco either rejects html files without the -o flag, issues a massive warning about potential data loss or writes the resulting documentation to *.html.html files, just in case.

Thanks.

On a side note, running rocco index.html multiple times and watching the file size grow exponentially is kind of fun. After 4 steps, I already had a 10MB html file, with escape sequeces escaped with escape sequences escaped with escape sequences escaped with escape sequences escaped with escape sequences.

http://rtomayko.github.com/rocco/ gives the standard gh-pages "Page does not exist!"

Whenever pygments see utf-8 chars in strings, for example "hello ąćęłńóśźż" I see:

*** Error while highlighting:
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc5 in position 91: 
   ordinal not in range(128)
(file "/usr/lib/python2.6/site-packages/Pygments-1.3.1-py2.6.egg/pygments/lexer.py", 
   line 148, in get_tokens)

I would like, if possible, to use another codec.

--Włodek

It's broken in the current master: ./bin/rocco ./bin/rocco generates ./.html instead of ./bin/rocco.html.

Hi,

first ,thanks for wonderful gem. I'm using rocco under jruby (1.6.2 - latest) on Mac OS X (latest). Just wanted to summarize issues here:

1. The same issue as fixed by pull request #57
2. The fork is not supported on this platform. The issue arise when using locally installed Pygmentise. The remote one (web service) works just fine. Maybe using someting like Albino will help ?

Cheers,
Maksym.

Now it does! mmikulicic's commit to support -o broke it. I fixed it in evaryont/rocco@a0b6ea3fbcb862c1ae3b7cfb6411902aabe026ef

When running the unit tests, test_issue10_utf8_processing fails when I run it under Ruby 1.9.3.

  2) Error:
test_issue10_utf8_processing(RoccoIssueTests):
ArgumentError: invalid byte sequence in UTF-8
    /Users/lambda/src/rocco/lib/rocco.rb:235:in `split'
    /Users/lambda/src/rocco/lib/rocco.rb:235:in `parse'
    /Users/lambda/src/rocco/lib/rocco.rb:134:in `initialize'
    /Users/lambda/src/rocco/test/test_reported_issues.rb:31:in `new'
    /Users/lambda/src/rocco/test/test_reported_issues.rb:31:in `test_issue10_utf8_processing'

This is because Ruby 1.9 is much more strict about encodings, instead of just reading bytes into the string and hoping you know how to interpret it, it actually keeps track of what encoding it expects the file and the string to be and transcodes between them. This means that we can no longer just read in the ISO-8859-1 as binary, and kind of hope that everything later on ignores it or knows how to cope. Instead, we need to explicitly choose to read the file as ISO-8859-1, and explicitly choose the encoding that we want the string to be in (probably UTF-8 as that's what everyone else will be expecting).

Running rocco thing.rb gives no such file to load -- bluecloth (LoadError).

It seems that the bin/rocco script (this section) is requiring rdiscount before rocco, so when rdiscount is missing, redcloth never gets loaded.

I didn't want to touch the code because as the comment suggests, it's a bit fragile.

Hi,

I'm just reposting a feature suggestion made to "docco" jashkenas/docco#41 .. as I now might start using rocco

Just an idea I tried.. I figured this could be useful to someone else besides me, esp those who do alot of mathematical programming

Mathjax supplies a javascript library on a CDN, and when you insert Latex into your HTML code, the formulas get rendered properly on the page. Combined with docco, this could make an amazing tool for annotating mathematical, or highly algorithmic code.

When I add this line of HTML to my resources/docco.jst template head, I can just insert Latex directly into my code comments, and the formulas show up perfectly in the generated HTML

-------------------------- HTML to go into HEAD tag -------------------------------------
script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML-full"

/script

---------------------------- END HTML -----------------------------------------------------------------------------

It would be great to have an option when using docco, to include the MathJax javascript libraries into the docco.jst template.
You might not want to place it in the template by default, but perhaps a command line option or something?

Is Javascript not one of the languages Rocco will generate docs for? Test run with two trivial example files:

$ cat javascript.js  
/* something */
function f() {
  // a comment
  alert( "hi" );
}   

$ cat ruby.rb 
module SpanishHarlem
  # purple drank
  def meth_od(code)
    puts "sup"
  end 

  # stuff
  puts "yo"
end 

$ bundle exec rocco ruby.rb javascript.js  
WARNING: Pygments not found. Using webservice.
pygmentize not in PATH; using pygments.appspot.com instead
rocco: ruby.rb -> ruby.html
rocco: javascript.js -> javascript.html

$ open ruby.html javascript.html

RESULT: generated HTML for ruby file looks fine, generated HTML for js file = no code / comments

We should support things like JavaDoc blocks, CSS multiline comments, and Python docblocks:

"""
Python!
"""

/**
 * Java and everyone else on the planet!
 */

It would be nice to drop the requirement that the comment character be specified on the command line. Given the filename, we should be able to make accurate guesses

See Pycco, for example.

It'd be great. Unfortunately changing require 'rdiscount' to require 'redcarpet' makes the tests (and rocco itself) fail: https://github.com/defunkt/rocco/compare/redcarpet

Mario posted this in a separate issue:

Nice :) Found 1 issue.

## H1
#Testing H1
foo 'bar'

foo statement appears before H1

The following works in Docco, but not in Rocco:

Level 1 Heading
===============

Level 2 Heading
---------------

Happily, the fix is trivial. In Docco, the regex for comments is:

# Does the line begin with a comment?
l.comment_matcher = new RegExp('^\\s*' + l.symbol + '\\s?')

Changing Rocco's comment pattern to:

@comment_pattern = Regexp.new("^\\s*#{@options[:comment_chars]}\s?")

Solves the problem for me. You'll have a pull request in a moment.

It'd be sweet.

Maybe this:

$ rocco -i lib/*.rb

Stack trace:

undefined method `empty?' for nil:NilClass
/Users/jamesrosen/.rvm/gems/ree-1.8.7-2011.03/gems/rocco-0.6/lib/rocco/layout.rb:30:in `sections'
/Users/jamesrosen/.rvm/gems/ree-1.8.7-2011.03/gems/rocco-0.6/lib/rocco/layout.rb:20:in `map'
/Users/jamesrosen/.rvm/gems/ree-1.8.7-2011.03/gems/rocco-0.6/lib/rocco/layout.rb:20:in `sections'
/Users/jamesrosen/.rvm/gems/ree-1.8.7-2011.03/gems/mustache-0.99.3/lib/mustache/context.rb:135:in `[]'
...

I'm using a custom language definition:

Rocco::COMMENT_STYLES['double-rb'] = {
  :single => "##",
  :multi  => { :start => '=begin', :middle => nil, :end => '=end' }
}

This allows me to differentiate between public API (## lines) and private API (# lines). Otherwise, nothing remarkable.

I wanted to put a comment or two on the right-hand side, right alongside the code as it would look like normally.. is this possible?

For example:

/**
 ## Downloads

* The [Standalone Release](http://github.com/pivotal/jasmine/downloads) is for simple, browser page, or console projects
* The [Jasmine Ruby Gem](http://github.com/pivotal/jasmine/wiki/A-ruby-project) is for Rails, Ruby, or Ruby-friendly development
* [Other Environments](http://github.com/pivotal/jasmine/wiki) are supported as well
*/

Turns into this HTML:

 <tr id="section-Downloads">
      <td class="docs">
        <div class="pilwrap">
          <a class="pilcrow" href="#section-Downloads">&#182;</a>
        </div>
        <h2>Downloads</h2>

<p>The <a href="http://github.com/pivotal/jasmine/downloads">Standalone Release</a> is for simple, browser page, or console projects
The <a href="http://github.com/pivotal/jasmine/wiki/A-ruby-project">Jasmine Ruby Gem</a> is for Rails, Ruby, or Ruby-friendly development
<a href="http://github.com/pivotal/jasmine/wiki">Other Environments</a> are supported as well</p>

We're treating this as part of the docs currently.

css upstream is no longer at http://jashkenas.github.com/docco/resources/docco.css, and as a result http://rtomayko.github.com/rocco/ is currently unstyled.

Fresh install on Ubuntu, I tried running rocco and got this:
$ rocco lib/*.rb /var/lib/gems/1.8/gems/rocco-0.8.2/lib/rocco.rb:447:in process_markdown': uninitialized constant Rocco::Markdown (NameError)
from /var/lib/gems/1.8/gems/rocco-0.8.2/lib/rocco.rb:391:in highlight' from /var/lib/gems/1.8/gems/rocco-0.8.2/lib/rocco.rb:129:in initialize'
from /var/lib/gems/1.8/gems/rocco-0.8.2/bin/rocco:67:in new' from /var/lib/gems/1.8/gems/rocco-0.8.2/bin/rocco:67 from /var/lib/gems/1.8/gems/rocco-0.8.2/bin/rocco:66:in each'
from /var/lib/gems/1.8/gems/rocco-0.8.2/bin/rocco:66
from /usr/local/bin/rocco:19:in load' from /usr/local/bin/rocco:19

Running Rdiscount 1.6.8, Bluecloth 2.2.0, Mustache 0.99.4, Pygments 1.4, Rubygems 1.7.2 and Ruby 1.8.7. Any other info I could provide to make your life easier?

I realise some people were having this issue and talk about it on #57, but for some reason it still doesn't work for me.

Cheers,
Leo

What if rocco could recurse subdirectories if a -r flag was used?

Suppose we have the following directory structure:

models/
    foo.coffee
    bar.coffee
views/
    foobar.coffee    
    barfoo.coffee    
controllers/
    barbar.coffee    
    foofoo.coffee
main.coffee

By calling, say, rocco -r *.coffee, we could generate docs for all the files. When using along with -o, it could create the respective subdirectories on the folder supplied for output.

Rocco displays nothing on the code side unless there is at least one comment. Now, you may ask, why are you using a literate programming tool and then adding no comments? In a multi-file project, there are sometimes files that are so simple they need no comments, and yet which you would like to be able to browse for reference purposes.

For an example of the problem, see Rocco's output for its own comment_styles.rb; it comes out empty.

Hey,

I've looked at this for a while, but don't have a great solution and am moving on. Something as simple as

heredoc <<-EOH
# comment
code
EOH

will break rocco. The 'code' for this section ends up being nil, after the "docs_html.zip(code_html)" runs, and layout.rb breaks with bad nil checks. The simple fix is to do better nil checks in layout.rb, specifically for 'code?' and 'empty?' in the sections method.

ie rocco -o html lib/*

will create the html/, but html output will still be produced in lib/