2010-03-11 11:25:35 +00:00
<!DOCTYPE html>
< html >
< head >
< meta http-equiv = "content-type" content = "text/html;charset=utf-8" >
< title > rocco.rb< / title >
< link rel = "stylesheet" href = "http://jashkenas.github.com/docco/resources/docco.css" >
< / head >
< body >
< div id = 'container' >
< div id = "background" > < / div >
2011-03-05 12:55:05 +00:00
< div id = "jump_to" >
Jump To …
< div id = "jump_wrapper" >
< div id = "jump_page" >
< a class = "source" href = "rocco.html" > rocco.rb< / a >
< a class = "source" href = "layout.html" > layout.rb< / a >
< a class = "source" href = "tasks.html" > tasks.rb< / a >
< / div >
< / div >
< / div >
2010-03-11 11:25:35 +00:00
< table cellspacing = 0 cellpadding = 0 >
< thead >
< tr >
< th class = docs > < h1 > rocco.rb< / h1 > < / th >
< th class = code > < / th >
< / tr >
< / thead >
< tbody >
< tr id = 'section-1' >
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-1" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > < strong > Rocco< / strong > is a Ruby port of < a href = "http://jashkenas.github.com/docco/" > Docco< / a > , the quick-and-dirty,
hundred-line-long, literate-programming-style documentation generator.< / p >
< p > Rocco reads Ruby source files and produces annotated source documentation
in HTML format. Comments are formatted with < a href = "http://daringfireball.net/projects/markdown/" > Markdown< / a > and presented
alongside syntax highlighted code so as to give an annotation effect.
This page is the result of running Rocco against < a href = "http://github.com/rtomayko/rocco/blob/master/lib/rocco.rb#commit" > its own source file< / a > .< / p >
< p > Most of this was written while waiting for < a href = "http://nodejs.org/" > node.js< / a > to build (so I
could use Docco!). Docco’ s gorgeous HTML and CSS are taken verbatim.
The main difference is that Rocco is written in Ruby instead of
< a href = "http://coffeescript.org/" > CoffeeScript< / a > and may be a bit easier to obtain and install in
existing Ruby environments or where node doesn’ t run yet.< / p >
< p > Install Rocco with Rubygems:< / p >
< pre > < code > gem install rocco
< / code > < / pre >
< p > Once installed, the < code > rocco< / code > command can be used to generate documentation
for a set of Ruby source files:< / p >
< pre > < code > rocco lib/*.rb
< / code > < / pre >
< p > The HTML files are written to the current working directory.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-2' >
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-2" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< h3 > Prerequisites< / h3 >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-3' >
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-3" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > We’ ll need a Markdown library. < a href = "http://github.com/rtomayko/rdiscount" > RDiscount< / a > , if we’ re lucky. Otherwise,
issue a warning and fall back on using BlueCloth.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "k" > begin< / span >
< span class = "nb" > require< / span > < span class = "s1" > ' rdiscount' < / span >
< span class = "k" > rescue< / span > < span class = "no" > LoadError< / span > < span class = "o" > => < / span > < span class = "n" > boom< / span >
2011-03-05 12:55:05 +00:00
< span class = "nb" > warn< / span > < span class = "s2" > " WARNING: < / span > < span class = "si" > #{< / span > < span class = "n" > boom< / span > < span class = "si" > }< / span > < span class = "s2" > . Trying bluecloth." < / span >
2010-03-11 11:25:35 +00:00
< span class = "nb" > require< / span > < span class = "s1" > ' bluecloth' < / span >
< span class = "no" > Markdown< / span > < span class = "o" > =< / span > < span class = "no" > BlueCloth< / span >
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-4' >
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-4" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > We use < a href = "http://defunkt.github.com/mustache/" > {{ mustache }}< / a > for
HTML templating.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "nb" > require< / span > < span class = "s1" > ' mustache' < / span > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-5' >
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-5" > ¶ < / a >
< / div >
< p > We use < code > Net::HTTP< / code > to highlight code via < a href = "http://pygments.appspot.com" > http://pygments.appspot.com< / a > < / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "nb" > require< / span > < span class = "s1" > ' net/http' < / span > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-6' >
< td class = docs >
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-6" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Code is run through < a href = "http://pygments.org/" > Pygments< / a > for syntax
2011-03-05 12:55:05 +00:00
highlighting. If it’ s not installed, locally, use a webservice.< / p >
2010-03-11 11:25:35 +00:00
< / td >
< td class = code >
2011-03-05 12:55:05 +00:00
< div class = 'highlight' > < pre > < span class = "kp" > include< / span > < span class = "no" > FileTest< / span >
< span class = "k" > if< / span > < span class = "o" > !< / span > < span class = "no" > ENV< / span > < span class = "o" > [< / span > < span class = "s1" > ' PATH' < / span > < span class = "o" > ].< / span > < span class = "n" > split< / span > < span class = "p" > (< / span > < span class = "s1" > ' :' < / span > < span class = "p" > )< / span > < span class = "o" > .< / span > < span class = "n" > any?< / span > < span class = "p" > {< / span > < span class = "o" > |< / span > < span class = "n" > dir< / span > < span class = "o" > |< / span > < span class = "n" > executable?< / span > < span class = "p" > (< / span > < span class = "s2" > " < / span > < span class = "si" > #{< / span > < span class = "n" > dir< / span > < span class = "si" > }< / span > < span class = "s2" > /pygmentize" < / span > < span class = "p" > )< / span > < span class = "p" > }< / span >
< span class = "nb" > warn< / span > < span class = "s2" > " WARNING: Pygments not found. Using webservice." < / span >
2010-03-11 11:25:35 +00:00
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-7' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-7" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< h3 > Public Interface< / h3 >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-8' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-8" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
2011-03-05 12:55:05 +00:00
< p > < code > Rocco.new< / code > takes a source < code > filename< / code > , an optional list of source filenames
for other documentation sources, an < code > options< / code > hash, and an optional < code > block< / code > .
The < code > options< / code > hash respects two members: < code > :language< / code > , which specifies which
Pygments lexer to use; and < code > :comment_chars< / code > , which specifies the comment
characters of the target language. The options default to < code > 'ruby'< / code > and < code > '#'< / code > ,
respectively.
When < code > block< / code > is given, it must read the contents of the file using whatever
means necessary and return it as a string. With no < code > block< / code > , the file is read
to retrieve data.< / p >
2010-03-11 11:25:35 +00:00
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "k" > class< / span > < span class = "nc" > Rocco< / span >
2011-03-05 12:55:05 +00:00
< span class = "no" > VERSION< / span > < span class = "o" > =< / span > < span class = "s1" > ' 0.5' < / span >
2010-03-11 11:25:35 +00:00
2011-03-05 12:55:05 +00:00
< span class = "k" > def< / span > < span class = "nf" > initialize< / span > < span class = "p" > (< / span > < span class = "n" > filename< / span > < span class = "p" > ,< / span > < span class = "n" > sources< / span > < span class = "o" > =[]< / span > < span class = "p" > ,< / span > < span class = "n" > options< / span > < span class = "o" > =< / span > < span class = "p" > {},< / span > < span class = "o" > & < / span > < span class = "n" > block< / span > < span class = "p" > )< / span >
2010-03-11 11:25:35 +00:00
< span class = "vi" > @file< / span > < span class = "o" > =< / span > < span class = "n" > filename< / span >
< span class = "vi" > @data< / span > < span class = "o" > =< / span >
< span class = "k" > if< / span > < span class = "nb" > block_given?< / span >
< span class = "k" > yield< / span >
< span class = "k" > else< / span >
< span class = "no" > File< / span > < span class = "o" > .< / span > < span class = "n" > read< / span > < span class = "p" > (< / span > < span class = "n" > filename< / span > < span class = "p" > )< / span >
< span class = "k" > end< / span >
2011-03-05 12:55:05 +00:00
< span class = "n" > defaults< / span > < span class = "o" > =< / span > < span class = "p" > {< / span >
< span class = "ss" > :language< / span > < span class = "o" > => < / span > < span class = "s1" > ' ruby' < / span > < span class = "p" > ,< / span >
< span class = "ss" > :comment_chars< / span > < span class = "o" > => < / span > < span class = "s1" > ' #' < / span > < span class = "p" > ,< / span >
< span class = "ss" > :template_file< / span > < span class = "o" > => < / span > < span class = "kp" > nil< / span >
< span class = "p" > }< / span >
< span class = "vi" > @options< / span > < span class = "o" > =< / span > < span class = "n" > defaults< / span > < span class = "o" > .< / span > < span class = "n" > merge< / span > < span class = "p" > (< / span > < span class = "n" > options< / span > < span class = "p" > )< / span >
< span class = "vi" > @sources< / span > < span class = "o" > =< / span > < span class = "n" > sources< / span >
< span class = "vi" > @comment_pattern< / span > < span class = "o" > =< / span > < span class = "no" > Regexp< / span > < span class = "o" > .< / span > < span class = "n" > new< / span > < span class = "p" > (< / span > < span class = "s2" > " ^< / span > < span class = "se" > \\< / span > < span class = "s2" > s*< / span > < span class = "si" > #{< / span > < span class = "vi" > @options< / span > < span class = "o" > [< / span > < span class = "ss" > :comment_chars< / span > < span class = "o" > ]< / span > < span class = "si" > }< / span > < span class = "se" > \s< / span > < span class = "s2" > ?" < / span > < span class = "p" > )< / span >
< span class = "vi" > @template_file< / span > < span class = "o" > =< / span > < span class = "vi" > @options< / span > < span class = "o" > [< / span > < span class = "ss" > :template_file< / span > < span class = "o" > ]< / span >
2010-03-11 11:25:35 +00:00
< span class = "vi" > @sections< / span > < span class = "o" > =< / span > < span class = "n" > highlight< / span > < span class = "p" > (< / span > < span class = "nb" > split< / span > < span class = "p" > (< / span > < span class = "n" > parse< / span > < span class = "p" > (< / span > < span class = "vi" > @data< / span > < span class = "p" > )))< / span >
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-9' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-9" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > The filename as given to < code > Rocco.new< / code > .< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "kp" > attr_reader< / span > < span class = "ss" > :file< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-10' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-10" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > A list of two-tuples representing each < em > section< / em > of the source file. Each
item in the list has the form: < code > [docs_html, code_html]< / code > , where both
elements are strings containing the documentation and source code HTML,
respectively.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "kp" > attr_reader< / span > < span class = "ss" > :sections< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-11' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-11" > ¶ < / a >
< / div >
< p > A list of all source filenames included in the documentation set. Useful
for building an index of other files.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "kp" > attr_reader< / span > < span class = "ss" > :sources< / span > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-12' >
< td class = docs >
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-12" > ¶ < / a >
< / div >
< p > An absolute path to a file that ought be used as a template for the
HTML-rendered documentation.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "kp" > attr_reader< / span > < span class = "ss" > :template_file< / span > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-13' >
< td class = docs >
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-13" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Generate HTML output for the entire document.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "nb" > require< / span > < span class = "s1" > ' rocco/layout' < / span >
< span class = "k" > def< / span > < span class = "nf" > to_html< / span >
2011-03-05 12:55:05 +00:00
< span class = "no" > Rocco< / span > < span class = "o" > ::< / span > < span class = "no" > Layout< / span > < span class = "o" > .< / span > < span class = "n" > new< / span > < span class = "p" > (< / span > < span class = "nb" > self< / span > < span class = "p" > ,< / span > < span class = "vi" > @template_file< / span > < span class = "p" > )< / span > < span class = "o" > .< / span > < span class = "n" > render< / span >
2010-03-11 11:25:35 +00:00
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-14' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-14" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< h3 > Internal Parsing and Highlighting< / h3 >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-15' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-15" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Parse the raw file data into a list of two-tuples. Each tuple has the
form < code > [docs, code]< / code > where both elements are arrays containing the
2011-03-05 12:55:05 +00:00
raw lines parsed from the input file. The first line is ignored if it
is a shebang line.< / p >
2010-03-11 11:25:35 +00:00
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "k" > def< / span > < span class = "nf" > parse< / span > < span class = "p" > (< / span > < span class = "n" > data< / span > < span class = "p" > )< / span >
< span class = "n" > sections< / span > < span class = "o" > =< / span > < span class = "o" > []< / span >
< span class = "n" > docs< / span > < span class = "p" > ,< / span > < span class = "n" > code< / span > < span class = "o" > =< / span > < span class = "o" > []< / span > < span class = "p" > ,< / span > < span class = "o" > []< / span >
2011-03-05 12:55:05 +00:00
< span class = "n" > lines< / span > < span class = "o" > =< / span > < span class = "n" > data< / span > < span class = "o" > .< / span > < span class = "n" > split< / span > < span class = "p" > (< / span > < span class = "s2" > " < / span > < span class = "se" > \n< / span > < span class = "s2" > " < / span > < span class = "p" > )< / span >
< span class = "n" > lines< / span > < span class = "o" > .< / span > < span class = "n" > shift< / span > < span class = "k" > if< / span > < span class = "n" > lines< / span > < span class = "o" > [< / span > < span class = "mi" > 0< / span > < span class = "o" > ]< / span > < span class = "o" > =~< / span > < span class = "sr" > /^\#\!/< / span >
< span class = "n" > lines< / span > < span class = "o" > .< / span > < span class = "n" > each< / span > < span class = "k" > do< / span > < span class = "o" > |< / span > < span class = "n" > line< / span > < span class = "o" > |< / span >
2010-03-11 11:25:35 +00:00
< span class = "k" > case< / span > < span class = "n" > line< / span >
2011-03-05 12:55:05 +00:00
< span class = "k" > when< / span > < span class = "vi" > @comment_pattern< / span >
2010-03-11 11:25:35 +00:00
< span class = "k" > if< / span > < span class = "n" > code< / span > < span class = "o" > .< / span > < span class = "n" > any?< / span >
< span class = "n" > sections< / span > < span class = "o" > < < < / span > < span class = "o" > [< / span > < span class = "n" > docs< / span > < span class = "p" > ,< / span > < span class = "n" > code< / span > < span class = "o" > ]< / span >
< span class = "n" > docs< / span > < span class = "p" > ,< / span > < span class = "n" > code< / span > < span class = "o" > =< / span > < span class = "o" > []< / span > < span class = "p" > ,< / span > < span class = "o" > []< / span >
< span class = "k" > end< / span >
< span class = "n" > docs< / span > < span class = "o" > < < < / span > < span class = "n" > line< / span >
< span class = "k" > else< / span >
< span class = "n" > code< / span > < span class = "o" > < < < / span > < span class = "n" > line< / span >
< span class = "k" > end< / span >
< span class = "k" > end< / span >
< span class = "n" > sections< / span > < span class = "o" > < < < / span > < span class = "o" > [< / span > < span class = "n" > docs< / span > < span class = "p" > ,< / span > < span class = "n" > code< / span > < span class = "o" > ]< / span > < span class = "k" > if< / span > < span class = "n" > docs< / span > < span class = "o" > .< / span > < span class = "n" > any?< / span > < span class = "o" > ||< / span > < span class = "n" > code< / span > < span class = "o" > .< / span > < span class = "n" > any?< / span >
< span class = "n" > sections< / span >
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-16' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-16" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Take the list of paired < em > sections< / em > two-tuples and split into two
separate lists: one holding the comments with leaders removed and
one with the code blocks.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "k" > def< / span > < span class = "nf" > split< / span > < span class = "p" > (< / span > < span class = "n" > sections< / span > < span class = "p" > )< / span >
< span class = "n" > docs_blocks< / span > < span class = "p" > ,< / span > < span class = "n" > code_blocks< / span > < span class = "o" > =< / span > < span class = "o" > []< / span > < span class = "p" > ,< / span > < span class = "o" > []< / span >
< span class = "n" > sections< / span > < span class = "o" > .< / span > < span class = "n" > each< / span > < span class = "k" > do< / span > < span class = "o" > |< / span > < span class = "n" > docs< / span > < span class = "p" > ,< / span > < span class = "n" > code< / span > < span class = "o" > |< / span >
2011-03-05 12:55:05 +00:00
< span class = "n" > docs_blocks< / span > < span class = "o" > < < < / span > < span class = "n" > docs< / span > < span class = "o" > .< / span > < span class = "n" > map< / span > < span class = "p" > {< / span > < span class = "o" > |< / span > < span class = "n" > line< / span > < span class = "o" > |< / span > < span class = "n" > line< / span > < span class = "o" > .< / span > < span class = "n" > sub< / span > < span class = "p" > (< / span > < span class = "vi" > @comment_pattern< / span > < span class = "p" > ,< / span > < span class = "s1" > ' ' < / span > < span class = "p" > )< / span > < span class = "p" > }< / span > < span class = "o" > .< / span > < span class = "n" > join< / span > < span class = "p" > (< / span > < span class = "s2" > " < / span > < span class = "se" > \n< / span > < span class = "s2" > " < / span > < span class = "p" > )< / span >
< span class = "n" > code_blocks< / span > < span class = "o" > < < < / span > < span class = "n" > code< / span > < span class = "o" > .< / span > < span class = "n" > map< / span > < span class = "k" > do< / span > < span class = "o" > |< / span > < span class = "n" > line< / span > < span class = "o" > |< / span >
< span class = "n" > tabs< / span > < span class = "o" > =< / span > < span class = "n" > line< / span > < span class = "o" > .< / span > < span class = "n" > match< / span > < span class = "p" > (< / span > < span class = "sr" > /^(\t+)/< / span > < span class = "p" > )< / span >
< span class = "n" > tabs< / span > < span class = "p" > ?< / span > < span class = "n" > line< / span > < span class = "o" > .< / span > < span class = "n" > sub< / span > < span class = "p" > (< / span > < span class = "sr" > /^\t+/< / span > < span class = "p" > ,< / span > < span class = "s1" > ' ' < / span > < span class = "o" > *< / span > < span class = "n" > tabs< / span > < span class = "o" > .< / span > < span class = "n" > captures< / span > < span class = "o" > [< / span > < span class = "mi" > 0< / span > < span class = "o" > ].< / span > < span class = "n" > length< / span > < span class = "p" > )< / span > < span class = "p" > :< / span > < span class = "n" > line< / span >
< span class = "k" > end< / span > < span class = "o" > .< / span > < span class = "n" > join< / span > < span class = "p" > (< / span > < span class = "s2" > " < / span > < span class = "se" > \n< / span > < span class = "s2" > " < / span > < span class = "p" > )< / span >
2010-03-11 11:25:35 +00:00
< span class = "k" > end< / span >
< span class = "o" > [< / span > < span class = "n" > docs_blocks< / span > < span class = "p" > ,< / span > < span class = "n" > code_blocks< / span > < span class = "o" > ]< / span >
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-17' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-17" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Take the result of < code > split< / code > and apply Markdown formatting to comments and
syntax highlighting to source code.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "k" > def< / span > < span class = "nf" > highlight< / span > < span class = "p" > (< / span > < span class = "n" > blocks< / span > < span class = "p" > )< / span >
< span class = "n" > docs_blocks< / span > < span class = "p" > ,< / span > < span class = "n" > code_blocks< / span > < span class = "o" > =< / span > < span class = "n" > blocks< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-18' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-18" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Combine all docs blocks into a single big markdown document with section
dividers and run through the Markdown processor. Then split it back out
into separate sections.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "n" > markdown< / span > < span class = "o" > =< / span > < span class = "n" > docs_blocks< / span > < span class = "o" > .< / span > < span class = "n" > join< / span > < span class = "p" > (< / span > < span class = "s2" > " < / span > < span class = "se" > \n\n< / span > < span class = "s2" > ##### DIVIDER< / span > < span class = "se" > \n\n< / span > < span class = "s2" > " < / span > < span class = "p" > )< / span >
< span class = "n" > docs_html< / span > < span class = "o" > =< / span > < span class = "no" > Markdown< / span > < span class = "o" > .< / span > < span class = "n" > new< / span > < span class = "p" > (< / span > < span class = "n" > markdown< / span > < span class = "p" > ,< / span > < span class = "ss" > :smart< / span > < span class = "p" > )< / span > < span class = "o" > .< / span >
< span class = "n" > to_html< / span > < span class = "o" > .< / span >
< span class = "nb" > split< / span > < span class = "p" > (< / span > < span class = "sr" > /\n*< h5> DIVIDER< \/h5> \n*/m< / span > < span class = "p" > )< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-19' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-19" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
2011-03-05 12:55:05 +00:00
< p > Combine all code blocks into a single big stream and run through either
< code > pygmentize(1)< / code > or < a href = "http://pygments.appspot.com" > http://pygments.appspot.com< / a > < / p >
2010-03-11 11:25:35 +00:00
< / td >
< td class = code >
2011-03-05 12:55:05 +00:00
< div class = 'highlight' > < pre > < span class = "n" > code_stream< / span > < span class = "o" > =< / span > < span class = "n" > code_blocks< / span > < span class = "o" > .< / span > < span class = "n" > join< / span > < span class = "p" > (< / span > < span class = "s2" > " < / span > < span class = "se" > \n\n< / span > < span class = "si" > #{< / span > < span class = "vi" > @options< / span > < span class = "o" > [< / span > < span class = "ss" > :comment_chars< / span > < span class = "o" > ]< / span > < span class = "si" > }< / span > < span class = "s2" > DIVIDER< / span > < span class = "se" > \n\n< / span > < span class = "s2" > " < / span > < span class = "p" > )< / span >
< span class = "k" > if< / span > < span class = "no" > ENV< / span > < span class = "o" > [< / span > < span class = "s1" > ' PATH' < / span > < span class = "o" > ].< / span > < span class = "n" > split< / span > < span class = "p" > (< / span > < span class = "s1" > ' :' < / span > < span class = "p" > )< / span > < span class = "o" > .< / span > < span class = "n" > any?< / span > < span class = "p" > {< / span > < span class = "o" > |< / span > < span class = "n" > dir< / span > < span class = "o" > |< / span > < span class = "n" > executable?< / span > < span class = "p" > (< / span > < span class = "s2" > " < / span > < span class = "si" > #{< / span > < span class = "n" > dir< / span > < span class = "si" > }< / span > < span class = "s2" > /pygmentize" < / span > < span class = "p" > )< / span > < span class = "p" > }< / span >
< span class = "n" > code_html< / span > < span class = "o" > =< / span > < span class = "n" > highlight_pygmentize< / span > < span class = "p" > (< / span > < span class = "n" > code_stream< / span > < span class = "p" > )< / span >
< span class = "k" > else< / span >
< span class = "n" > code_html< / span > < span class = "o" > =< / span > < span class = "n" > highlight_webservice< / span > < span class = "p" > (< / span > < span class = "n" > code_stream< / span > < span class = "p" > )< / span >
2010-03-11 11:25:35 +00:00
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-20' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-20" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Do some post-processing on the pygments output to split things back
into sections and remove partial < code > < pre> < / code > blocks.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "n" > code_html< / span > < span class = "o" > =< / span > < span class = "n" > code_html< / span > < span class = "o" > .< / span >
2011-03-05 12:55:05 +00:00
< span class = "nb" > split< / span > < span class = "p" > (< / span > < span class = "sr" > /\n*< span class=" c.?" > < / span > < span class = "si" > #{< / span > < span class = "vi" > @options< / span > < span class = "o" > [< / span > < span class = "ss" > :comment_chars< / span > < span class = "o" > ]< / span > < span class = "si" > }< / span > < span class = "sr" > DIVIDER< \/span> \n*/m< / span > < span class = "p" > )< / span > < span class = "o" > .< / span >
2010-03-11 11:25:35 +00:00
< span class = "n" > map< / span > < span class = "p" > {< / span > < span class = "o" > |< / span > < span class = "n" > code< / span > < span class = "o" > |< / span > < span class = "n" > code< / span > < span class = "o" > .< / span > < span class = "n" > sub< / span > < span class = "p" > (< / span > < span class = "sr" > /\n?< div class=" highlight" > < pre> /m< / span > < span class = "p" > ,< / span > < span class = "s1" > ' ' < / span > < span class = "p" > )< / span > < span class = "p" > }< / span > < span class = "o" > .< / span >
< span class = "n" > map< / span > < span class = "p" > {< / span > < span class = "o" > |< / span > < span class = "n" > code< / span > < span class = "o" > |< / span > < span class = "n" > code< / span > < span class = "o" > .< / span > < span class = "n" > sub< / span > < span class = "p" > (< / span > < span class = "sr" > /\n?< \/pre> < \/div> \n/m< / span > < span class = "p" > ,< / span > < span class = "s1" > ' ' < / span > < span class = "p" > )< / span > < span class = "p" > }< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-21' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-21" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > Lastly, combine the docs and code lists back into a list of two-tuples.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "n" > docs_html< / span > < span class = "o" > .< / span > < span class = "n" > zip< / span > < span class = "p" > (< / span > < span class = "n" > code_html< / span > < span class = "p" > )< / span >
2011-03-05 12:55:05 +00:00
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
< tr id = 'section-22' >
< td class = docs >
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-22" > ¶ < / a >
< / div >
< p > We < code > popen< / code > a read/write pygmentize process in the parent and
then fork off a child process to write the input.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "k" > def< / span > < span class = "nf" > highlight_pygmentize< / span > < span class = "p" > (< / span > < span class = "n" > code< / span > < span class = "p" > )< / span >
< span class = "n" > code_html< / span > < span class = "o" > =< / span > < span class = "kp" > nil< / span >
< span class = "nb" > open< / span > < span class = "p" > (< / span > < span class = "s2" > " |pygmentize -l < / span > < span class = "si" > #{< / span > < span class = "vi" > @options< / span > < span class = "o" > [< / span > < span class = "ss" > :language< / span > < span class = "o" > ]< / span > < span class = "si" > }< / span > < span class = "s2" > -O encoding=utf-8 -f html" < / span > < span class = "p" > ,< / span > < span class = "s1" > ' r+' < / span > < span class = "p" > )< / span > < span class = "k" > do< / span > < span class = "o" > |< / span > < span class = "n" > fd< / span > < span class = "o" > |< / span >
< span class = "n" > pid< / span > < span class = "o" > =< / span >
< span class = "nb" > fork< / span > < span class = "p" > {< / span >
< span class = "n" > fd< / span > < span class = "o" > .< / span > < span class = "n" > close_read< / span >
< span class = "n" > fd< / span > < span class = "o" > .< / span > < span class = "n" > write< / span > < span class = "n" > code< / span >
< span class = "n" > fd< / span > < span class = "o" > .< / span > < span class = "n" > close_write< / span >
< span class = "nb" > exit!< / span >
< span class = "p" > }< / span >
< span class = "n" > fd< / span > < span class = "o" > .< / span > < span class = "n" > close_write< / span >
< span class = "n" > code_html< / span > < span class = "o" > =< / span > < span class = "n" > fd< / span > < span class = "o" > .< / span > < span class = "n" > read< / span >
< span class = "n" > fd< / span > < span class = "o" > .< / span > < span class = "n" > close_read< / span >
< span class = "no" > Process< / span > < span class = "o" > .< / span > < span class = "n" > wait< / span > < span class = "p" > (< / span > < span class = "n" > pid< / span > < span class = "p" > )< / span >
< span class = "k" > end< / span >
< span class = "n" > code_html< / span >
< span class = "k" > end< / span >
< / pre > < / div >
< / td >
< / tr >
< tr id = 'section-23' >
< td class = docs >
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-23" > ¶ < / a >
< / div >
< p > Pygments is not one of those things that’ s trivial for a ruby user to install,
so we’ ll fall back on a webservice to highlight the code if it isn’ t available.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < span class = "k" > def< / span > < span class = "nf" > highlight_webservice< / span > < span class = "p" > (< / span > < span class = "n" > code< / span > < span class = "p" > )< / span >
< span class = "no" > Net< / span > < span class = "o" > ::< / span > < span class = "no" > HTTP< / span > < span class = "o" > .< / span > < span class = "n" > post_form< / span > < span class = "p" > (< / span >
< span class = "no" > URI< / span > < span class = "o" > .< / span > < span class = "n" > parse< / span > < span class = "p" > (< / span > < span class = "s1" > ' http://pygments.appspot.com/' < / span > < span class = "p" > ),< / span >
< span class = "p" > {< / span > < span class = "s1" > ' lang' < / span > < span class = "o" > => < / span > < span class = "vi" > @options< / span > < span class = "o" > [< / span > < span class = "s1" > ' language' < / span > < span class = "o" > ]< / span > < span class = "p" > ,< / span > < span class = "s1" > ' code' < / span > < span class = "o" > => < / span > < span class = "n" > code< / span > < span class = "p" > }< / span >
< span class = "p" > )< / span > < span class = "o" > .< / span > < span class = "n" > body< / span >
2010-03-11 11:25:35 +00:00
< span class = "k" > end< / span >
< span class = "k" > end< / span > < / pre > < / div >
< / td >
< / tr >
2011-03-05 12:55:05 +00:00
< tr id = 'section-24' >
2010-03-11 11:25:35 +00:00
< td class = docs >
2011-03-05 12:55:05 +00:00
< div class = "pilwrap" >
< a class = "pilcrow" href = "#section-24" > ¶ < / a >
2010-03-11 11:25:35 +00:00
< / div >
< p > And that’ s it.< / p >
< / td >
< td class = code >
< div class = 'highlight' > < pre > < / pre > < / div >
< / td >
< / tr >
< / table >
< / div >
< / body >
