Your SlideShare is downloading. ×
Docco.coffee
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Saving this for later?

Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime - even offline.

Text the download link to your phone

Standard text messaging rates apply

Docco.coffee

819
views

Published on


0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
819
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. 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 doccoIf Node.js doesnt run on your platform, or youd prefer a moreconvenient package, get Rocco, the Ruby port thats available as agem. If youre writing shell scripts, try Shocco, a port for thePOSIX shell. Both are by Ryan Tomayko. If Pythons more yourspeed, take a look at Nick Fitzgeralds Pycco.Main Documentation Generation FunctionsGenerate the documentation for a source file by reading it in, generate_documentation = (source, callback) ->splitting it up into comment/code sections, highlighting them for fs.readFile source, "utf-8", (error, code) -> throw error if errorthe appropriate language, and merging them into an HTML sections = parse source, codetemplate. highlight source, sections, -> generate_html source, sections callback()Given a string of source code, parse out each comment and the parse = (source, code) ->code that follows it, and create an individual section for it. lines = code.split n sections = []Sections take the form: language = get_language source { has_code = docs_text = code_text = docs_text: ... docs_html: ... save = (docs, code) -> code_text: ... sections.push docs_text: docs, code_text: code code_html: ... } 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 sectionsHighlights a single chunk of CoffeeScript code, using Pygments highlight = (source, sections, callback) ->over stdio, and runs the text of its corresponding comment language = get_language source pygments = spawn pygmentize, [-l, language.name, -f, html, -O, encothrough Markdown, using the Github-flavored-Markdown output = modification of Showdown.js. pygments.stderr.addListener data, (error) -> console.error error if errorWe process the entire file in a single call to Pygments by inserting pygments.stdout.addListener data, (result) ->little marker comments between each section and then splitting output += result if resultthe result string wherever our markers occur. pygments.addListener exit, ->
  • 2. 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 pygments.stdin.end()Once all of the code is finished highlighting, we can generate the generate_html = (source, sections) ->HTML file and write out the documentation. Pass the completed title = path.basename source dest = destination sourcesections into the template found in resources/docco.jst html = docco_template { title: title, sections: sections, sources: sources, path: path, destination: } console.log "docco: #{source} -> #{dest}" fs.writeFile dest, htmlHelpers & SetupRequire our external dependencies, including Showdown.js (the fs = require fsJavaScript implementation of Markdown). path = require path showdown = require(./../vendor/showdown).Showdown {spawn, exec} = require child_processA list of the languages that Docco supports, mapping the file languages =extension to the name of the Pygments lexer and the symbol that .coffee: name: coffee-script, symbol: #indicates a comment. To add another language to Doccos .js:repertoire, add it here. name: javascript, symbol: // .rb: name: ruby, symbol: # .py: name: python, symbol: #Build out the appropriate matchers and delimiters for each for ext, l of languageslanguage.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 the l.divider_text = n + l.symbol + DIVIDERnboundaries between sections.The mirror of divider_text that we expect Pygments to return. l.divider_html = new RegExp(n*<span class="c1?"> + l.symbol + DIVIDER</We can split on this to recover the original sections. Note: the classis "c" for Python and "c1" for the other languagesGet the current language were documenting, based on the get_language = (source) -> languages[path.extname(source)]extension.Compute the destination HTML path for an input source file path. destination = (filepath) ->If the source is lib/example.coffee , the HTML will be at docs/ + path.basename(filepath, path.extname(filepath)) + .htmldocs/example.htmlEnsure that the destination directory exists. ensure_directory = (callback) -> exec mkdir -p docs, -> callback()Micro-templating, originally by John Resig, borrowed by way of template = (str) ->Underscore.js. new Function obj, var p=[],print=function(){p.push.apply(p,arguments);}; + with(obj){p.push( + str.replace(/[rtn]/g, " ") .replace(/(?=[^<]*%>)/g,"t") .split("").join("") .split("t").join("") .replace(/<%=(.+?)%>/g, ",$1,") .split(<%).join(");") .split(%>).join("p.push(") + ");}return p.join();"
  • 3. Create the template that we will use to generate the Docco HTML docco_template = template fs.readFileSync(__dirname + /../resources/docco.jstpage.The CSS styles wed like to apply to the documentation. docco_styles = fs.readFileSync(__dirname + /../resources/resources/docco.cssThe 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, sources = process.ARGV.sort()generate the documentation. 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.leng next_file()