docco.coffeeDocco is a quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTMLthat displays your comments alongside your code. Comments arepassed through Markdown, and code is passed through Pygmentssyntax highlighting. This page is the result of running Doccoagainst its own source file.

If you install Docco, you can run it from the command-line:

docco src/*.coffee

...will generate linked HTML documentation for the named sourcefiles, saving it into a docs folder.

The source for Docco is available on GitHub, and released underthe MIT license.

To install Docco, first make sure you have Node.js, Pygments(install the latest dev version of Pygments from its Mercurialrepo), and CoffeeScript. Then, with NPM:

sudo npm install docco

If Node.js doesn't run on your platform, or you'd prefer a moreconvenient package, get Rocco, the Ruby port that's available as agem. If you're writing shell scripts, try Shocco, a port for thePOSIX shell. Both are by Ryan Tomayko. If Python's more yourspeed, take a look at Nick Fitzgerald's Pycco.

Main Documentation Generation Functions

Generate the documentation for a source file by reading it in,splitting it up into comment/code sections, highlighting them forthe appropriate language, and merging them into an HTMLtemplate.

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()

Given a string of source code, parse out each comment and thecode that follows it, and create an individual section for it.Sections take the form:

{ docs_text: ... docs_html: ... code_text: ... code_html: ...}

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 if 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

Highlights a single chunk of CoffeeScript code, using Pygmentsover stdio, and runs the text of its corresponding commentthrough Markdown, using the Github-flavored-Markdownmodification of Showdown.js.

We process the entire file in a single call to Pygments by insertinglittle marker comments between each section and then splittingthe result string wherever our markers occur.

highlight = (source, sections, callback) -> language = get_language source pygments = spawn 'pygmentize', ['-l', language.name, '-f', 'html', '-O', 'encoding=utf-8'] output = '' pygments.stderr.addListener 'data', (error) -> console.error error if error 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() pygments.stdin.write((section.code_text for section in sections).join(language.divider_text)) pygments.stdin.end()

Once all of the code is finished highlighting, we can generate theHTML file and write out the documentation. Pass the completedsections into the template found in resources/docco.jst

generate_html = (source, sections) -> title = path.basename source dest = destination source html = docco_template { title: title, sections: sections, sources: sources, path: path, destination: destination } console.log "docco: #{source} -> #{dest}" fs.writeFile dest, html

Helpers & Setup

Require our external dependencies, including Showdown.js (theJavaScript implementation of Markdown).

fs = require 'fs'path = require 'path'showdown = require('./../vendor/showdown').Showdown{spawn, exec} = require 'child_process'

A list of the languages that Docco supports, mapping the fileextension to the name of the Pygments lexer and the symbol thatindicates a comment. To add another language to Docco'srepertoire, add it here.

languages = '.coffee': name: 'coffee-script', symbol: '#' '.js': name: 'javascript', symbol: '//' '.rb': name: 'ruby', symbol: '#' '.py': name: 'python', symbol: '#'

Build out the appropriate matchers and delimiters for eachlanguage.

for ext, l of languages

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

Ignore hashbangs) l.comment_filter = new RegExp('^#![/]')

The dividing token we feed into Pygments, to delimit theboundaries between sections.

l.divider_text = '\n' + l.symbol + 'DIVIDER\n'

The mirror of divider_text that we expect Pygments to return.We can split on this to recover the original sections. Note: the classis "c" for Python and "c1" for the other languages

l.divider_html = new RegExp('\\n*<span class="c1?">' + l.symbol + 'DIVIDER<\\/span>\\n*')

Get the current language we're documenting, based on theextension.

get_language = (source) -> languages[path.extname(source)]

Compute the destination HTML path for an input source file path.If the source is lib/example.coffee , the HTML will be atdocs/example.html

destination = (filepath) -> 'docs/' + path.basename(filepath, path.extname(filepath)) + '.html'

Ensure that the destination directory exists. ensure_directory = (callback) -> exec 'mkdir -p docs', -> callback()

Micro-templating, originally by John Resig, borrowed by way ofUnderscore.js.

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('');"

Create the template that we will use to generate the Docco HTMLpage.

docco_template = template fs.readFileSync(__dirname + '/../resources/docco.jst').toString()

The CSS styles we'd like to apply to the documentation. docco_styles = fs.readFileSync(__dirname + '/../resources/resources/docco.css').toString()

The start of each Pygments highlight block. highlight_start = '<div class="highlight"><pre>'

The end of each Pygments highlight block. highlight_end = '</pre></div>'

Run the script. For each source file passed in as an argument,generate the documentation.

sources = process.ARGV.sort()if sources.length ensure_directory -> fs.writeFile 'docs/resources/docco.css', docco_styles files = sources.slice(0) next_file = -> generate_documentation files.shift(), next_file if files.length next_file()