Refactor: extract reusable classes

[maxlinc]

Overview

The trickiest part of Docco/Rocco is parsing source from any language and splitting it into segments of documentation and code. The majority of the code and tests are about how to parse the source files into a usable data structure.

So I'd like a Rocco API that lets me parse and use these segments, without assuming:

• The documentation segments are markdown that I want rendered
• I want syntax highlighting on the source code
• I want the final result to be HTML

There's more notes below explaining some of the things I'm interested in doing where those assumptions don't make sense. I'm not actually saying Rocco should implement any of the features below. I just want to reuse Rocco's parsing and data structure so other projects can do interesting things.

Other uses for the Rocco "segments" data structure

(Non-HTML) Templates for static site generators

One of my biggest issues with Docco/Rocco has been that I want to embed it as part of a larger site. The CSS and HTML layout is designed for a full page, it doesn't work well if it's embedded in another template so you can have site navigation.

Although that could be fixed with custom CSS & templates, I am often using a static site generator (like Middleman, Jekyll, or DocPad) that gives me most of Rocco's features anyways - other than parsing the source code. So rather than a custom HTML template, I'd really like to just have Rocco output other formats like Markdown to reStructuredText so the site generator can take care of converting to HTML, syntax highlighting, and applying the layout. Those formats work fine for the linear template, and while parallel is trickier, slate has managed a parallel view from pure Markdown (using CSS & JS).

Extracting snippets from larger files

I'm also interested in things that have very little in common with the original Docco output, like exacting just certain snippets from the source code. A lot of documentation doesn't show the full example, just the relevant snippet. In the case of slate, related snippets are shown in several languages. I'd like a utility where I could exact just the relevant snippets, based on comments. So given code like:

# Say hi
puts 'Hello, World!'

class HelloWorldApp {
    public static void main(String[] args) {
        // Say hi
        System.out.println("Hello World!");
        // done
    }
}

If I ran something like:

%w(hello_world.rb HelloWorld.java).each do |file|
  puts "Relevant snippet: <% Rocco::CodeSegmenter.new(file).code_with_label /Say hi/ %>
end

Outputs:

Relevant snippet: puts 'Hello, World!'
Relevant snippet: System.out.println("Hello World!");

(In other words, I can get just the interesting part of a file to inline in docs, especially for languages like Java with a lot of boilerplate)