Skip to content

Commit

Permalink
Updating Docco for CoffeeScript 0.9.0
Browse files Browse the repository at this point in the history
  • Loading branch information
jashkenas committed Aug 3, 2010
1 parent 5049213 commit 5edd8cf
Show file tree
Hide file tree
Showing 3 changed files with 96 additions and 98 deletions.
6 changes: 3 additions & 3 deletions Cakefile
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
exec: require('child_process').exec
exec = require('child_process').exec

option '-p', '--prefix [DIR]', 'set the installation prefix for `cake install`'

task 'install', 'install the `docco` command into /usr/local (or --prefix)', (options) ->
base: options.prefix or '/usr/local'
lib: base + '/lib/docco'
base = options.prefix or '/usr/local'
lib = base + '/lib/docco'
exec([
'mkdir -p ' + lib
'cp -rf bin README resources vendor docco.coffee ' + lib
Expand Down
99 changes: 49 additions & 50 deletions docco.coffee
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,10 @@
# 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.
generate_documentation: (source, callback) ->
generate_documentation = (source, callback) ->
fs.readFile source, (error, code) ->
throw error if error
sections: parse source, code.toString()
sections = parse source, code.toString()
highlight source, sections, ->
generate_html source, sections
callback()
Expand All @@ -52,26 +52,23 @@ generate_documentation: (source, callback) ->
# 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
}
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 has_code
save docs_text, code_text
has_code: docs_text: code_text: ''
has_code = docs_text = code_text = ''
docs_text += line.replace(language.comment_matcher, '') + '\n'
else
has_code: true
has_code = yes
code_text += line + '\n'
save docs_text, code_text
sections
Expand All @@ -83,31 +80,31 @@ parse: (source, code) ->
# 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.
highlight: (source, sections, callback) ->
language: get_language source
pygments: spawn 'pygmentize', ['-l', language.name, '-f', 'html']
output: ''
highlight = (source, sections, callback) ->
language = get_language source
pygments = spawn 'pygmentize', ['-l', language.name, '-f', 'html']
output = ''
pygments.stderr.addListener 'data', (error) ->
puts 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
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
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 the HTML file
# and write out the documentation. Pass the completed sections into the template
# found in `resources/docco.jst`
generate_html: (source, sections) ->
title: path.basename source
dest: destination source
html: docco_template {
generate_html = (source, sections) ->
title = path.basename source
dest = destination source
html = docco_template {
title: title, sections: sections, sources: sources, path: path, destination: destination
}
puts "docco: $source -> $dest"
Expand All @@ -117,49 +114,51 @@ generate_html: (source, sections) ->

# Require our external dependencies, including **Showdown.js**
# (the JavaScript implementation of Markdown).
fs: require 'fs'
path: require 'path'
showdown: require('./vendor/showdown').Showdown
{spawn: spawn, exec: exec}: require('child_process')
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 file extension to
# the name of the Pygments lexer and the symbol that indicates a comment. To
# add another language to Docco's repertoire, add it here.
languages: {
'.coffee': {name: 'coffee-script', symbol: '#'}
'.js': {name: 'javascript', symbol: '//'}
'.rb': {name: 'ruby', symbol: '#'}
}
languages =
'.coffee':
name: 'coffee-script', symbol: '#'
'.js':
name: 'javascript', symbol: '//'
'.rb':
name: 'ruby', symbol: '#'

# Build out the appropriate matchers and delimiters for each language.
for ext, l of languages

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

# The dividing token we feed into Pygments, to delimit the boundaries between
# sections.
l.divider_text: '\n' + l.symbol + 'DIVIDER\n'
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.
l.divider_html: new RegExp('\\n*<span class="c1">' + l.symbol + 'DIVIDER<\\/span>\\n*')
l.divider_html = new RegExp('\\n*<span class="c1">' + l.symbol + 'DIVIDER<\\/span>\\n*')

# Get the current language we're documenting, based on the extension.
get_language: (source) -> languages[path.extname(source)]
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 at `docs/example.html`
destination: (filepath) ->
destination = (filepath) ->
'docs/' + path.basename(filepath, path.extname(filepath)) + '.html'

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

# Micro-templating, originally by John Resig, borrowed by way of
# [Underscore.js](http://documentcloud.github.com/underscore/).
template: (str) ->
template = (str) ->
new Function 'obj',
'var p=[],print=function(){p.push.apply(p,arguments);};' +
'with(obj){p.push(\'' +
Expand All @@ -173,23 +172,23 @@ template: (str) ->
"');}return p.join('');"

# Create the template that we will use to generate the Docco HTML page.
docco_template: template fs.readFileSync(__dirname + '/resources/docco.jst').toString()
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/docco.css').toString()
docco_styles = fs.readFileSync(__dirname + '/resources/docco.css').toString()

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

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

# Run the script.
# For each source file passed in as an argument, generate the documentation.
sources: process.ARGV.sort()
sources = process.ARGV.sort()
if sources.length
ensure_directory ->
fs.writeFile 'docs/docco.css', docco_styles
files: sources.slice(0)
next_file: -> generate_documentation files.shift(), next_file if files.length
files = sources.slice(0)
next_file = -> generate_documentation files.shift(), next_file if files.length
next_file()
Loading

0 comments on commit 5edd8cf

Please sign in to comment.