Permalink
Browse files

first semi-release of Docco. 0.1.0, I guess.

  • Loading branch information...
1 parent 5ae3a05 commit 97874303c038fec22819625c40510b5dbe8a93c5 @jashkenas committed Mar 5, 2010
Showing with 197 additions and 42 deletions.
  1. +0 −1 .gitignore
  2. +13 −1 README
  3. +51 −35 docco.coffee
  4. +122 −0 index.html
  5. +11 −5 resources/docco.css
View
@@ -1,3 +1,2 @@
output
-*.html
docs
View
14 README
@@ -1 +1,13 @@
-A Literate Programming -style documentation generator, for CoffeeScript, for now.
+ ____
+/\ _`\
+\ \ \/\ \ ___ ___ ___ ___
+ \ \ \ \ \ / __`\ /'___\ /'___\ / __`\
+ \ \ \_\ \ /\ \ \ \ /\ \__/ /\ \__/ /\ \ \ \
+ \ \____/ \ \____/ \ \____\ \ \____\ \ \____/
+ \/___/ \/___/ \/____/ \/____/ \/___/
+
+
+Docco is a quick-and-dirty, hundred-line-long, literate-programming-style
+documentation generator. For more information, see:
+
+http://jashkenas.github.com/docco/
View
@@ -1,24 +1,28 @@
-# **Docco** is a quick and dirty literate-programming-style documentation generator.
-# It produces HTML that displays your comments alongside your code. Comments
-# are passed through [Markdown](http://daringfireball.net/projects/markdown/syntax),
-# and code is passed through [Pygments](http://pygments.org/) syntax highlighting.
+# **Docco** is a quick-and-dirty, hundred-line-long, literate-programming-style
+# documentation generator. It produces HTML that displays your comments
+# alongside your code. Comments are passed through
+# [Markdown](http://daringfireball.net/projects/markdown/syntax), and code is
+# passed through [Pygments](http://pygments.org/) syntax highlighting.
+# This page is the result of running Docco against its own source file.
#
-# Currently, Docco can be run from the command-line like so:
+# If you install Docco, you can run it from the command-line:
#
-# coffee docco.coffee -- path/to/target.coffee
+# docco src/*.coffee
+#
+# ...will generate linked HTML documentation for the named source files, saving
+# it into a `docs` folder.
+#
+# To install Docco, first make sure you have [Node.js](http://nodejs.org/) and
+# [CoffeeScript](http://coffeescript.org/). Then, to install system-wide in
+# `/usr/local`:
+#
+# sudo cake install
-# External dependencies, including **Showdown.js** (the JavaScript implementation
-# of Markdown).
-require.paths.unshift __dirname
-fs: require 'fs'
-path: require 'path'
-showdown: require('vendor/showdown').Showdown
+#### Main Documentation Generation Functions
# Generate the documentation for a source file by reading it in, splitting it
-# up into comment/code sections, highlighting them, and generating the corresponding
-# HTML. For the moment, we run a separate **Pygments** process for each section,
-# which is quite wasteful. In the future, we should either use a JavaScript-based
-# syntax highlighter, or insert section delimiters and run a single **Pygments** process.
+# up into comment/code sections, highlighting them for the appropriate language,
+# and generating the corresponding HTML.
generate_documentation: (source) ->
ensure_directory ->
set_language source
@@ -31,7 +35,10 @@ generate_documentation: (source) ->
# Highlights a single chunk of CoffeeScript code, using **Pygments** over stdio,
# and runs the text of its corresponding comment through **Markdown**, using the
-# **Github-flavored-Markdown** modification of **Showdown.js**.
+# **Github-flavored-Markdown** modification of [Showdown.js](http://attacklab.net/showdown/).
+#
+# We process the entire file in a single call to Pygments by inserting little
+# marker comments between each section and then splitting the results.
highlight: (source, sections, callback) ->
pygments: process.createChildProcess 'pygmentize', ['-l', language.name, '-f', 'html']
output: ''
@@ -49,7 +56,8 @@ highlight: (source, sections, callback) ->
pygments.write((section.code_text for section in sections).join(language.divider_text))
pygments.close()
-# Parse out each comments and the code that follows into a individual section.
+# Given a string of source code, parse out each comment and the code that
+# follows it into an individual section.
# Sections take the form:
#
# {
@@ -83,54 +91,62 @@ parse: (code) ->
sections
# Once all of the code is finished highlighting, we can generate the HTML file
-# and write out the documentation. In the future, it would be nice to extract
-# these HTML strings into a template.
+# and write out the documentation. The HTML is generated by running the template
+# found in `resources/docco.jst`, and passing it the completed sections.
generate_html: (source, sections) ->
title: path.basename source
html: docco_template {
title: title, sections: sections, sources: sources, path: path, destination: destination
}
fs.writeFile destination(source), html
-# Helpers
-# -------
+#### Helpers & Setup
+
+# Require our external dependencies, including **Showdown.js**
+# (the JavaScript implementation of Markdown).
+require.paths.unshift __dirname
+fs: require 'fs'
+path: require 'path'
+showdown: require('vendor/showdown').Showdown
-# A map of the languages that Docco supports.
-# File extension mapped to Pygments name and comment symbol.
+# 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: '#'}
}
-# The language of the current sourcefile.
+# The language object, containing the appropriate matchers and delimiters for
+# for the current sourcefile's language.
language: null
-# Set the current language we're documenting, based on the extension of the
-# source file.
+# Set the current language we're documenting, based on the extension.
set_language: (source) ->
l: language: languages[path.extname(source)]
- # Does the line begin with a comment? Handle `#` and `//` -style comments.
+ # Does the line begin with a comment?
l.comment_matcher: new RegExp('^\\s*' + l.symbol + '\\s?')
- # The dividing token we feed into Pygments, so that we can get all of the
- # sections to be highlighted in a single pass.
+ # The dividing token we feed into Pygments, to delimit the boundaries between
+ # sections.
l.divider_text: '\n' + l.symbol + 'DIVIDER\n'
- # The mirror of the divider that Pygments returns, that we split on in order
- # to recover the original sections.
+ # 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*')
-# Compute the destination HTML path for an input source file.
+# 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, borrowed from John Resig, by way of
+# Micro-templating, originally by John Resig, borrowed by way of
# [Underscore.js](http://documentcloud.github.com/underscore/).
template: (str) ->
new Function 'obj',
@@ -145,7 +161,7 @@ template: (str) ->
.split('%>').join("p.push('") +
"');}return p.join('');"
-# The template that we use to generate the Docco HTML page.
+# Create the template that we will use to generate the Docco HTML page.
docco_template: template fs.readFileSync __dirname + '/resources/docco.jst'
# The CSS styles we'd like to apply to the documentation.
Oops, something went wrong.

0 comments on commit 9787430

Please sign in to comment.