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) ->
- fs.readFile source, "utf-8", (error, code) ->
+and merging them into an HTML template. generate_documentation = (source, callback) ->
+ fs.readFile source, "utf-8", (error, code) ->
throw error if error
sections = parse source, code
highlight source, sections, ->
@@ -45,14 +45,14 @@
code_text: ...
code_html: ...
}
- parse = (source, 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
+ save = (docs, code) ->
+ sections.push docs_text: docs, code_text: code
for line in lines
if line.match language.comment_matcher
@@ -70,13 +70,13 @@
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) ->
+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) ->
+ pygments.stderr.addListener 'data', (error) ->
puts error if error
- pygments.stdout.addListener 'data', (result) ->
+ pygments.stdout.addListener 'data', (result) ->
output += result if result
pygments.addListener 'exit', ->
output = output.replace(highlight_start, '').replace(highlight_end, '')
@@ -88,11 +88,11 @@
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) ->
+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
+ title: title, sections: sections, sources: sources, path: path, destination: destination
}
puts "docco: #{source} -> #{dest}"
fs.writeFile dest, htmlRequire our external dependencies, including Showdown.js @@ -104,20 +104,20 @@ 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: '#'
+ name: 'coffee-script', symbol: '#'
'.js':
- name: 'javascript', symbol: '//'
+ name: 'javascript', symbol: '//'
'.rb':
- name: 'ruby', symbol: '#'
+ name: 'ruby', symbol: '#'
'.py':
- name: 'python', symbol: '#'Build out the appropriate matchers and delimiters for each language.
for ext, l of languagesDoes the line begin with a comment?
l.comment_matcher = new RegExp('^\\s*' + l.symbol + '\\s?')The dividing token we feed into Pygments, to delimit the boundaries between + name: 'python', symbol: '#'
Build out the appropriate matchers and delimiters for each language.
for ext, l of languagesDoes the line begin with a comment?
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'The mirror of divider_text 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
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)]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) ->
- 'docs/' + path.basename(filepath, path.extname(filepath)) + '.html'Ensure that the destination directory exists.
ensure_directory = (callback) ->
+Note: the class is "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 the extension.
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) ->
+ '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 of -Underscore.js.
template = (str) ->
+Underscore.js. template = (str) ->
new Function 'obj',
'var p=[],print=function(){p.push.apply(p,arguments);};' +
'with(obj){p.push(\'' +