paige

<!DOCTYPE html> <html> <head> <title>rocco.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="rocco.css" /> </head> <body> <div id="navbar"> <h3>Paige.js - The quickie-wiki Github project page generator</h3> </div> <div id="container"> <div id="background"></div> <div id="jump_to"> Jump To … <div id="jump_wrapper"> <div id="jump_page"> <a class="source" href="index.html">Index</a> <a class="source" href="paige.html"> paige.coffee </a> <a class="source" href="rocco.html"> rocco.coffee </a> </div> </div> </div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> rocco.coffee </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-1">¶</a> </div> <h3>Rocco</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">¶</a> </div> Rocco is a minimal alteration on the original Docco, by <a href="https://github.com/jashkenas">Jeremy Ashkenas</a>. Rocco was incorporated into the Paige project for ease of customization and extendability that are beyond the scope of the original Docco project. </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">¶</a> </div> What follows is the original, unaltered documentation for Docco from Jeremy Ashkenas. </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">¶</a> </div> <h3>Main Documentation Generation Functions</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">¶</a> </div> Generate the documentation for a source file by reading it in, splitting it up into comment/code sections, highlighting them for the appropriate language, and merging them into an HTML template. </td> <td class="code"> <div class="highlight"><pre>generate_documentation = (source, callback) -> fs.readFile source, "utf-8", (error, code) -> throw error if error sections = parse source, code highlight source, sections, -> generate_html source, sections callback()</pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</a> </div> Given a string of source code, parse out each comment and the code that follows it, and create an individual section for it. Sections take the form: <pre><code>{ docs_text: ... docs_html: ... code_text: ... code_html: ... }</code></pre> </td> <td class="code"> <div class="highlight"><pre>parse = (source, code) -> lines = code.split '\n' sections = [] language = get_language source has_code = docs_text = code_text = '' save = (docs, code) -> sections.push docs_text: docs, code_text: code for line in lines if line.match(language.comment_matcher) and not line.match(language.comment_filter) if has_code save docs_text, code_text has_code = docs_text = code_text = '' docs_text += line.replace(language.comment_matcher, '') + '\n' else has_code = yes code_text += line + '\n' save docs_text, code_text sections</pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">¶</a> </div> Highlights a single chunk of CoffeeScript code, using Pygments over stdio, and runs the text of its corresponding comment through Markdown, using <a href="http://attacklab.net/showdown/">Showdown.js</a>. We process the entire file in a single call to Pygments by inserting little marker comments between each section and then splitting the result string wherever our markers occur. </td> <td class="code"> <div class="highlight"><pre>highlight = (source, sections, callback) -> language = get_language source pygments = spawn 'pygmentize', ['-l', language.name, '-f', 'html', '-O', 'encoding=utf-8,tabsize=2'] output = '' pygments.stderr.addListener 'data', (error) -> console.error error.toString() if error pygments.stdin.addListener 'error', (error) -> console.error "Could not use Pygments to highlight the source." process.exit 1 pygments.stdout.addListener 'data', (result) -> output += result if result pygments.addListener 'exit', -> output = output.replace(highlight_start, '').replace(highlight_end, '') fragments = output.split language.divider_html for section, i in sections section.code_html = highlight_start + fragments[i] + highlight_end section.docs_html = showdown.makeHtml section.docs_text callback() if pygments.stdin.writable pygments.stdin.write((section.code_text for section in sections).join(language.divider_text)) pygments.stdin.end()</pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">¶</a> </div> Once all of the code is finished highlighting, we can generate the HTML file and write out the documentation. Pass the completed sections into the template found in <code>resources/rocco.jst</code> </td> <td class="code"> <div class="highlight"><pre>generate_html = (source, sections) -> title = path.basename source dest = destination source html = rocco_template { header: configuration.header, subheader: configuration.subheader, title: title, sections: sections, sources: sources, path: path, destination: destination } console.log "rocco: #{source} -> #{dest}" fs.writeFile dest, html</pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">¶</a> </div> <h3>Helpers & Setup</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">¶</a> </div> Require our external dependencies, including Showdown.js (the JavaScript implementation of Markdown). </td> <td class="code"> <div class="highlight"><pre>fs = require 'fs' path = require 'path' showdown = require('./../vendor/showdown').Showdown {spawn, exec} = require 'child_process'</pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">¶</a> </div> A list of the languages that rocco supports, mapping the file extension to the name of the Pygments lexer and the symbol that indicates a comment. To add another language to rocco's repertoire, add it here. </td> <td class="code"> <div class="highlight"><pre>languages = '.coffee': name: 'coffee-script', symbol: '#' '.js': name: 'javascript', symbol: '//' '.rb': name: 'ruby', symbol: '#' '.py': name: 'python', symbol: '#'</pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</a> </div> Build out the appropriate matchers and delimiters for each language. </td> <td class="code"> <div class="highlight"><pre>for ext, l of languages</pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">¶</a> </div> Does the line begin with a comment? </td> <td class="code"> <div class="highlight"><pre> l.comment_matcher = new RegExp('^\\s*' + l.symbol + '\\s?')</pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">¶</a> </div> Ignore <a href="http://en.wikipedia.org/wiki/Shebang_(Unix">hashbangs</a>) and interpolations... </td> <td class="code"> <div class="highlight"><pre> l.comment_filter = new RegExp('(^#![/]|^\\s*#\\{)')</pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">¶</a> </div> The dividing token we feed into Pygments, to delimit the boundaries between sections. </td> <td class="code"> <div class="highlight"><pre> l.divider_text = '\n' + l.symbol + 'DIVIDER\n'</pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">¶</a> </div> The mirror of <code>divider_text</code> that we expect Pygments to return. We can split on this to recover the original sections. Note: the class is "c" for Python and "c1" for the other languages </td> <td class="code"> <div class="highlight"><pre> l.divider_html = new RegExp('\\n*' + l.symbol + 'DIVIDER<\\/span>\\n*')</pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">¶</a> </div> Get the current language we're documenting, based on the extension. </td> <td class="code"> <div class="highlight"><pre>get_language = (source) -> languages[path.extname(source)]</pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">¶</a> </div> Compute the destination HTML path for an input source file path. If the source is <code>lib/example.coffee</code>, the HTML will be at <code>docs/example.html</code> </td> <td class="code"> <div class="highlight"><pre>destination = (filepath) -> configuration.output + '/' + path.basename(filepath, path.extname(filepath)) + '.html'</pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</a> </div> Ensure that the destination directory exists. </td> <td class="code"> <div class="highlight"><pre>ensure_directory = (dir, callback) -> exec "mkdir -p #{dir}", -> callback()</pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">¶</a> </div> Micro-templating, originally by John Resig, borrowed by way of <a href="http://documentcloud.github.com/underscore/">Underscore.js</a>. </td> <td class="code"> <div class="highlight"><pre>template = (str) -> new Function 'obj', 'var p=[],print=function(){p.push.apply(p,arguments);};' + 'with(obj){p.push(\'' + str.replace(/[\r\t\n]/g, " ") .replace(/'(?=[^<]*%>)/g,"\t") .split("'").join("\\'") .split("\t").join("'") .replace(/<%=(.+?)%>/g, "',$1,'") .split('<%').join("');") .split('%>').join("p.push('") + "');}return p.join('');"</pre></div> </td> </tr> <tr id="section-21"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-21">¶</a> </div> Create the template that we will use to generate the rocco HTML page. </td> <td class="code"> <div class="highlight"><pre>rocco_template = template fs.readFileSync(__dirname + '/../resources/rocco.jst').toString()</pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-22">¶</a> </div> The CSS styles we'd like to apply to the documentation. </td> <td class="code"> <div class="highlight"><pre>rocco_styles = fs.readFileSync(__dirname + '/../resources/rocco.css').toString()</pre></div> </td> </tr> <tr id="section-23"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-23">¶</a> </div> The start of each Pygments highlight block. </td> <td class="code"> <div class="highlight"><pre>highlight_start = '<div class="highlight"><pre>'</pre></div> </td> </tr> <tr id="section-24"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-24">¶</a> </div> The end of each Pygments highlight block. </td> <td class="code"> <div class="highlight"><pre>highlight_end = '</pre></div>'</pre></div> </td> </tr> <tr id="section-25"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-25">¶</a> </div> <h3>Modifications</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-26"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-26">¶</a> </div> Slight modification to the way rocco ran initially. This gives us a little more freedom to experiment with rocco's inputs and configurability. </td> <td class="code"> <div class="highlight"><pre>sources = [] configuration = {} rocco = (srcs, config) -> sources = srcs configuration = config fs.writeFile "#{configuration.output}/rocco.css", rocco_styles files = sources.slice(0) next_file = -> generate_documentation files.shift(), next_file if files.length next_file() module.exports = rocco </pre></div> </td> </tr> </tbody> </table> </div> </body> </html>