Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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

  • Loading branch information...
commit 97874303c038fec22819625c40510b5dbe8a93c5 1 parent 5ae3a05
@jashkenas jashkenas authored
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  .gitignore
@@ -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
86 docco.coffee
@@ -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,8 +91,8 @@ 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 {
@@ -92,37 +100,45 @@ generate_html: (source, sections) ->
}
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'
@@ -130,7 +146,7 @@ destination: (filepath) ->
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.
View
122 index.html
@@ -0,0 +1,122 @@
+<!DOCTYPE html> <html> <head> <title>docco.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="resources/docco.css" /> </head> <body> <div id="container"> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> docco.coffee </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-1">#</a> </div> <p><strong>Docco</strong> 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
+<a href="http://daringfireball.net/projects/markdown/syntax">Markdown</a>, and code is
+passed through <a href="http://pygments.org/">Pygments</a> syntax highlighting.
+This page is the result of running Docco against its own source file.</p>
+
+<p>If you install Docco, you can run it from the command-line:</p>
+
+<pre><code>docco src/*.coffee
+</code></pre>
+
+<p>...will generate linked HTML documentation for the named source files, saving
+it into a <code>docs</code> folder.</p>
+
+<p>To install Docco, first make sure you have <a href="http://nodejs.org/">Node.js</a> and
+<a href="http://coffeescript.org/">CoffeeScript</a>. Then, to install system-wide in
+<code>/usr/local</code>:</p>
+
+<pre><code>sudo cake install
+</code></pre> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-2">#</a> </div> <h3>Main Documentation Generation Functions</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-3">#</a> </div> <p>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 generating the corresponding HTML.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">generate_documentation: </span><span class="p">(</span><span class="nx">source</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nx">ensure_directory</span> <span class="o">-&gt;</span>
+ <span class="nx">set_language</span> <span class="nx">source</span>
+ <span class="nv">code: </span><span class="nx">fs</span><span class="p">.</span><span class="nx">readFile</span> <span class="nx">source</span><span class="p">,</span> <span class="p">(</span><span class="nx">error</span><span class="p">,</span> <span class="nx">code</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="k">throw</span> <span class="nx">error</span> <span class="k">if</span> <span class="nx">error</span>
+ <span class="nv">sections: </span><span class="nx">parse</span> <span class="nx">code</span>
+ <span class="nx">highlight</span> <span class="nx">source</span><span class="p">,</span> <span class="nx">sections</span><span class="p">,</span> <span class="o">-&gt;</span>
+ <span class="nx">generate_html</span> <span class="nx">source</span><span class="p">,</span> <span class="nx">sections</span>
+ <span class="nx">fs</span><span class="p">.</span><span class="nx">writeFile</span> <span class="s1">&#39;docs/resources/docco.css&#39;</span><span class="p">,</span> <span class="nx">docco_styles</span></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-4">#</a> </div> <p>Highlights a single chunk of CoffeeScript code, using <strong>Pygments</strong> over stdio,
+and runs the text of its corresponding comment through <strong>Markdown</strong>, using the
+<strong>Github-flavored-Markdown</strong> modification of <a href="http://attacklab.net/showdown/">Showdown.js</a>.</p>
+
+<p>We process the entire file in a single call to Pygments by inserting little
+marker comments between each section and then splitting the results.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">highlight: </span><span class="p">(</span><span class="nx">source</span><span class="p">,</span> <span class="nx">sections</span><span class="p">,</span> <span class="nx">callback</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nv">pygments: </span><span class="nx">process</span><span class="p">.</span><span class="nx">createChildProcess</span> <span class="s1">&#39;pygmentize&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;-l&#39;</span><span class="p">,</span> <span class="nx">language</span><span class="p">.</span><span class="nx">name</span><span class="p">,</span> <span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;html&#39;</span><span class="p">]</span>
+ <span class="nv">output: </span><span class="s1">&#39;&#39;</span>
+ <span class="nx">pygments</span><span class="p">.</span><span class="nx">addListener</span> <span class="s1">&#39;error&#39;</span><span class="p">,</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nx">process</span><span class="p">.</span><span class="nx">stdio</span><span class="p">.</span><span class="nx">writeError</span> <span class="nx">error</span> <span class="k">if</span> <span class="nx">error</span>
+ <span class="nx">pygments</span><span class="p">.</span><span class="nx">addListener</span> <span class="s1">&#39;output&#39;</span><span class="p">,</span> <span class="p">(</span><span class="nx">result</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nx">output</span> <span class="o">+=</span> <span class="nx">result</span> <span class="k">if</span> <span class="nx">result</span>
+ <span class="nx">pygments</span><span class="p">.</span><span class="nx">addListener</span> <span class="s1">&#39;exit&#39;</span><span class="p">,</span> <span class="o">-&gt;</span>
+ <span class="nv">output: </span><span class="nx">output</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="nx">highlight_start</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">).</span><span class="nx">replace</span><span class="p">(</span><span class="nx">highlight_end</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span>
+ <span class="nv">fragments: </span><span class="nx">output</span><span class="p">.</span><span class="nx">split</span> <span class="nx">language</span><span class="p">.</span><span class="nx">divider_html</span>
+ <span class="k">for</span> <span class="nx">section</span><span class="p">,</span> <span class="nx">i</span> <span class="k">in</span> <span class="nx">sections</span>
+ <span class="nv">section.code_html: </span><span class="nx">highlight_start</span> <span class="o">+</span> <span class="nx">fragments</span><span class="p">[</span><span class="nx">i</span><span class="p">]</span> <span class="o">+</span> <span class="nx">highlight_end</span>
+ <span class="nv">section.docs_html: </span><span class="nx">showdown</span><span class="p">.</span><span class="nx">makeHtml</span> <span class="nx">section</span><span class="p">.</span><span class="nx">docs_text</span>
+ <span class="nx">callback</span><span class="p">()</span>
+ <span class="nx">pygments</span><span class="p">.</span><span class="nx">write</span><span class="p">((</span><span class="nx">section</span><span class="p">.</span><span class="nx">code_text</span> <span class="k">for</span> <span class="nx">section</span> <span class="k">in</span> <span class="nx">sections</span><span class="p">).</span><span class="nx">join</span><span class="p">(</span><span class="nx">language</span><span class="p">.</span><span class="nx">divider_text</span><span class="p">))</span>
+ <span class="nx">pygments</span><span class="p">.</span><span class="nx">close</span><span class="p">()</span></pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-5">#</a> </div> <p>Given a string of source code, parse out each comment and the code that
+follows it into an individual section.
+Sections take the form:</p>
+
+<pre><code>{
+ docs_text: ...
+ docs_html: ...
+ code_text: ...
+ code_html: ...
+}
+</code></pre> </td> <td class="code"> <div class="highlight"><pre><span class="nv">parse: </span><span class="p">(</span><span class="nx">code</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nv">lines: </span><span class="nx">code</span><span class="p">.</span><span class="nx">split</span> <span class="s1">&#39;\n&#39;</span>
+ <span class="nv">sections: </span><span class="p">[]</span>
+ <span class="nv">has_code: docs_text: code_text: </span><span class="s1">&#39;&#39;</span>
+
+ <span class="nv">save: </span><span class="p">(</span><span class="nx">docs</span><span class="p">,</span> <span class="nx">code</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nx">sections</span><span class="p">.</span><span class="nx">push</span> <span class="p">{</span>
+ <span class="nv">docs_text: </span><span class="nx">docs</span>
+ <span class="nv">code_text: </span><span class="nx">code</span>
+ <span class="p">}</span>
+
+ <span class="k">for</span> <span class="nx">line</span> <span class="k">in</span> <span class="nx">lines</span>
+ <span class="k">if</span> <span class="nx">line</span><span class="p">.</span><span class="nx">match</span> <span class="nx">language</span><span class="p">.</span><span class="nx">comment_matcher</span>
+ <span class="k">if</span> <span class="nx">has_code</span>
+ <span class="nx">save</span> <span class="nx">docs_text</span><span class="p">,</span> <span class="nx">code_text</span>
+ <span class="nv">has_code: docs_text: code_text: </span><span class="s1">&#39;&#39;</span>
+ <span class="nx">docs_text</span> <span class="o">+=</span> <span class="nx">line</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="nx">language</span><span class="p">.</span><span class="nx">comment_matcher</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">+</span> <span class="s1">&#39;\n&#39;</span>
+ <span class="k">else</span>
+ <span class="nv">has_code: </span><span class="kc">true</span>
+ <span class="nx">code_text</span> <span class="o">+=</span> <span class="nx">line</span> <span class="o">+</span> <span class="s1">&#39;\n&#39;</span>
+ <span class="nx">save</span> <span class="nx">docs_text</span><span class="p">,</span> <span class="nx">code_text</span>
+ <span class="nx">sections</span></pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-6">#</a> </div> <p>Once all of the code is finished highlighting, we can generate the HTML file
+and write out the documentation. The HTML is generated by running the template
+found in <code>resources/docco.jst</code>, and passing it the completed sections.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">generate_html: </span><span class="p">(</span><span class="nx">source</span><span class="p">,</span> <span class="nx">sections</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nv">title: </span><span class="nx">path</span><span class="p">.</span><span class="nx">basename</span> <span class="nx">source</span>
+ <span class="nv">html: </span> <span class="nx">docco_template</span> <span class="p">{</span>
+ <span class="nv">title: </span><span class="nx">title</span><span class="p">,</span> <span class="nv">sections: </span><span class="nx">sections</span><span class="p">,</span> <span class="nv">sources: </span><span class="nx">sources</span><span class="p">,</span> <span class="nv">path: </span><span class="nx">path</span><span class="p">,</span> <span class="nv">destination: </span><span class="nx">destination</span>
+ <span class="p">}</span>
+ <span class="nx">fs</span><span class="p">.</span><span class="nx">writeFile</span> <span class="nx">destination</span><span class="p">(</span><span class="nx">source</span><span class="p">),</span> <span class="nx">html</span></pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-7">#</a> </div> <h3>Helpers &amp; Setup</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-8">#</a> </div> <p>Require our external dependencies, including <strong>Showdown.js</strong>
+(the JavaScript implementation of Markdown).</p> </td> <td class="code"> <div class="highlight"><pre><span class="nx">require</span><span class="p">.</span><span class="nx">paths</span><span class="p">.</span><span class="nx">unshift</span> <span class="nx">__dirname</span>
+<span class="nv">fs: </span> <span class="nx">require</span> <span class="s1">&#39;fs&#39;</span>
+<span class="nv">path: </span> <span class="nx">require</span> <span class="s1">&#39;path&#39;</span>
+<span class="nv">showdown: </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;vendor/showdown&#39;</span><span class="p">).</span><span class="nx">Showdown</span></pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-9">#</a> </div> <p>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.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">languages: </span><span class="p">{</span>
+ <span class="s1">&#39;.coffee&#39;</span><span class="o">:</span> <span class="p">{</span><span class="nv">name: </span><span class="s1">&#39;coffee-script&#39;</span><span class="p">,</span> <span class="nv">symbol: </span><span class="s1">&#39;#&#39;</span><span class="p">}</span>
+ <span class="s1">&#39;.js&#39;</span><span class="o">:</span> <span class="p">{</span><span class="nv">name: </span><span class="s1">&#39;javascript&#39;</span><span class="p">,</span> <span class="nv">symbol: </span><span class="s1">&#39;//&#39;</span><span class="p">}</span>
+ <span class="s1">&#39;.rb&#39;</span><span class="o">:</span> <span class="p">{</span><span class="nv">name: </span><span class="s1">&#39;ruby&#39;</span><span class="p">,</span> <span class="nv">symbol: </span><span class="s1">&#39;#&#39;</span><span class="p">}</span>
+<span class="p">}</span></pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-10">#</a> </div> <p>The language object, containing the appropriate matchers and delimiters for
+for the current sourcefile's language.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">language: </span><span class="kc">null</span></pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-11">#</a> </div> <p>Set the current language we're documenting, based on the extension.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">set_language: </span><span class="p">(</span><span class="nx">source</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nv">l: language: </span><span class="nx">languages</span><span class="p">[</span><span class="nx">path</span><span class="p">.</span><span class="nx">extname</span><span class="p">(</span><span class="nx">source</span><span class="p">)]</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-12">#</a> </div> <p>Does the line begin with a comment?</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nv">l.comment_matcher: </span><span class="k">new</span> <span class="nb">RegExp</span><span class="p">(</span><span class="s1">&#39;^\\s*&#39;</span> <span class="o">+</span> <span class="nx">l</span><span class="p">.</span><span class="nx">symbol</span> <span class="o">+</span> <span class="s1">&#39;\\s?&#39;</span><span class="p">)</span></pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-13">#</a> </div> <p>The dividing token we feed into Pygments, to delimit the boundaries between
+sections.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nv">l.divider_text: </span><span class="s1">&#39;\n&#39;</span> <span class="o">+</span> <span class="nx">l</span><span class="p">.</span><span class="nx">symbol</span> <span class="o">+</span> <span class="s1">&#39;DIVIDER\n&#39;</span></pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-14">#</a> </div> <p>The mirror of <code>divider_text</code> that we expect Pygments to return. We can split
+on this to recover the original sections.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nv">l.divider_html: </span><span class="k">new</span> <span class="nb">RegExp</span><span class="p">(</span><span class="s1">&#39;\\n*&lt;span class=&quot;c1&quot;&gt;&#39;</span> <span class="o">+</span> <span class="nx">l</span><span class="p">.</span><span class="nx">symbol</span> <span class="o">+</span> <span class="s1">&#39;DIVIDER&lt;\\/span&gt;\\n*&#39;</span><span class="p">)</span></pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-15">#</a> </div> <p>Compute the destination HTML path for an input source file path. If the source
+is <code>lib/example.coffee</code>, the HTML will be at <code>docs/example.html</code></p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">destination: </span><span class="p">(</span><span class="nx">filepath</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="s1">&#39;docs/&#39;</span> <span class="o">+</span> <span class="nx">path</span><span class="p">.</span><span class="nx">basename</span><span class="p">(</span><span class="nx">filepath</span><span class="p">,</span> <span class="nx">path</span><span class="p">.</span><span class="nx">extname</span><span class="p">(</span><span class="nx">filepath</span><span class="p">))</span> <span class="o">+</span> <span class="s1">&#39;.html&#39;</span></pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-16">#</a> </div> <p>Ensure that the destination directory exists.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">ensure_directory: </span><span class="p">(</span><span class="nx">callback</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="nx">exec</span> <span class="s1">&#39;mkdir -p docs&#39;</span><span class="p">,</span> <span class="o">-&gt;</span> <span class="nx">callback</span><span class="p">()</span></pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-17">#</a> </div> <p>Micro-templating, originally by John Resig, borrowed by way of
+<a href="http://documentcloud.github.com/underscore/">Underscore.js</a>.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">template: </span><span class="p">(</span><span class="nx">str</span><span class="p">)</span> <span class="o">-&gt;</span>
+ <span class="k">new</span> <span class="nb">Function</span> <span class="s1">&#39;obj&#39;</span><span class="p">,</span>
+ <span class="s1">&#39;var p=[],print=function(){p.push.apply(p,arguments);};&#39;</span> <span class="o">+</span>
+ <span class="s1">&#39;with(obj){p.push(\&#39;&#39;</span> <span class="o">+</span>
+ <span class="nx">str</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/[\r\t\n]/g</span><span class="p">,</span> <span class="s2">&quot; &quot;</span><span class="p">)</span>
+ <span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/&#39;(?=[^&lt;]*%&gt;)/g</span><span class="p">,</span><span class="s2">&quot;\t&quot;</span><span class="p">)</span>
+ <span class="p">.</span><span class="nx">split</span><span class="p">(</span><span class="s2">&quot;&#39;&quot;</span><span class="p">).</span><span class="nx">join</span><span class="p">(</span><span class="s2">&quot;\\&#39;&quot;</span><span class="p">)</span>
+ <span class="p">.</span><span class="nx">split</span><span class="p">(</span><span class="s2">&quot;\t&quot;</span><span class="p">).</span><span class="nx">join</span><span class="p">(</span><span class="s2">&quot;&#39;&quot;</span><span class="p">)</span>
+ <span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/&lt;%=(.+?)%&gt;/g</span><span class="p">,</span> <span class="s2">&quot;&#39;,$1,&#39;&quot;</span><span class="p">)</span>
+ <span class="p">.</span><span class="nx">split</span><span class="p">(</span><span class="s1">&#39;&lt;%&#39;</span><span class="p">).</span><span class="nx">join</span><span class="p">(</span><span class="s2">&quot;&#39;);&quot;</span><span class="p">)</span>
+ <span class="p">.</span><span class="nx">split</span><span class="p">(</span><span class="s1">&#39;%&gt;&#39;</span><span class="p">).</span><span class="nx">join</span><span class="p">(</span><span class="s2">&quot;p.push(&#39;&quot;</span><span class="p">)</span> <span class="o">+</span>
+ <span class="s2">&quot;&#39;);}return p.join(&#39;&#39;);&quot;</span></pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-18">#</a> </div> <p>Create the template that we will use to generate the Docco HTML page.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">docco_template: </span> <span class="nx">template</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span> <span class="nx">__dirname</span> <span class="o">+</span> <span class="s1">&#39;/resources/docco.jst&#39;</span></pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-19">#</a> </div> <p>The CSS styles we'd like to apply to the documentation.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">docco_styles: </span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span> <span class="nx">__dirname</span> <span class="o">+</span> <span class="s1">&#39;/resources/resources/docco.css&#39;</span></pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-20">#</a> </div> <p>The start of each Pygments highlight block.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">highlight_start: </span><span class="s1">&#39;&lt;div class=&quot;highlight&quot;&gt;&lt;pre&gt;&#39;</span></pre></div> </td> </tr> <tr id="section-21"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-21">#</a> </div> <p>The end of each Pygments highlight block.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">highlight_end: </span> <span class="s1">&#39;&lt;/pre&gt;&lt;/div&gt;&#39;</span></pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-22">#</a> </div> <p>Run the script.
+For each source file passed in as an argument, generate the documentation.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">sources: </span><span class="nx">process</span><span class="p">.</span><span class="nx">ARGV</span><span class="p">.</span><span class="nx">sort</span><span class="p">()</span>
+<span class="nx">generate_documentation</span> <span class="nx">source</span> <span class="k">for</span> <span class="nx">source</span> <span class="k">in</span> <span class="nx">sources</span>
+
+</pre></div> </td> </tr> </tbody> </table> </div> </body> </html>
View
16 resources/docco.css
@@ -13,10 +13,10 @@ a {
color: #261a3b;
}
p {
- margin: 0;
+ margin: 0 0 15px 0;
}
-h1 {
- margin: 40px 0 0 0;
+h1, h2, h3, h4, h5, h6 {
+ margin: 40px 0 15px 0;
}
#jump_to, #jump_page {
background: white;
@@ -68,7 +68,7 @@ table td {
max-width: 500px;
min-width: 500px;
min-height: 5px;
- padding: 10px 30px 16px 50px;
+ padding: 10px 30px 1px 50px;
vertical-align: top;
text-align: left;
}
@@ -76,6 +76,12 @@ table td {
margin: 15px 0 15px;
padding-left: 15px;
}
+ .docs p tt, .docs p code {
+ background: #f8f8ff;
+ border: 1px solid #dedede;
+ font-size: 12px;
+ padding: 0 0.2em;
+ }
.octowrap {
position: relative;
}
@@ -99,7 +105,7 @@ table td {
background: #f5f5ff;
border-left: 1px solid #e5e5ee;
}
- pre {
+ pre, tt, code {
font-size: 12px; line-height: 18px;
font-family: Monaco, Consolas, "Lucida Console", monospace;
margin: 0; padding: 0;
Please sign in to comment.
Something went wrong with that request. Please try again.