Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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

  • Loading branch information...
commit 97874303c038fec22819625c40510b5dbe8a93c5 1 parent 5ae3a05
Jeremy Ashkenas jashkenas authored
1  .gitignore
... ... @@ -1,3 +1,2 @@
1 1 output
2   -*.html
3 2 docs
14 README
... ... @@ -1 +1,13 @@
1   -A Literate Programming -style documentation generator, for CoffeeScript, for now.
  1 + ____
  2 +/\ _`\
  3 +\ \ \/\ \ ___ ___ ___ ___
  4 + \ \ \ \ \ / __`\ /'___\ /'___\ / __`\
  5 + \ \ \_\ \ /\ \ \ \ /\ \__/ /\ \__/ /\ \ \ \
  6 + \ \____/ \ \____/ \ \____\ \ \____\ \ \____/
  7 + \/___/ \/___/ \/____/ \/____/ \/___/
  8 +
  9 +
  10 +Docco is a quick-and-dirty, hundred-line-long, literate-programming-style
  11 +documentation generator. For more information, see:
  12 +
  13 +http://jashkenas.github.com/docco/
86 docco.coffee
... ... @@ -1,24 +1,28 @@
1   -# **Docco** is a quick and dirty literate-programming-style documentation generator.
2   -# It produces HTML that displays your comments alongside your code. Comments
3   -# are passed through [Markdown](http://daringfireball.net/projects/markdown/syntax),
4   -# and code is passed through [Pygments](http://pygments.org/) syntax highlighting.
  1 +# **Docco** is a quick-and-dirty, hundred-line-long, literate-programming-style
  2 +# documentation generator. It produces HTML that displays your comments
  3 +# alongside your code. Comments are passed through
  4 +# [Markdown](http://daringfireball.net/projects/markdown/syntax), and code is
  5 +# passed through [Pygments](http://pygments.org/) syntax highlighting.
  6 +# This page is the result of running Docco against its own source file.
5 7 #
6   -# Currently, Docco can be run from the command-line like so:
  8 +# If you install Docco, you can run it from the command-line:
7 9 #
8   -# coffee docco.coffee -- path/to/target.coffee
  10 +# docco src/*.coffee
  11 +#
  12 +# ...will generate linked HTML documentation for the named source files, saving
  13 +# it into a `docs` folder.
  14 +#
  15 +# To install Docco, first make sure you have [Node.js](http://nodejs.org/) and
  16 +# [CoffeeScript](http://coffeescript.org/). Then, to install system-wide in
  17 +# `/usr/local`:
  18 +#
  19 +# sudo cake install
9 20
10   -# External dependencies, including **Showdown.js** (the JavaScript implementation
11   -# of Markdown).
12   -require.paths.unshift __dirname
13   -fs: require 'fs'
14   -path: require 'path'
15   -showdown: require('vendor/showdown').Showdown
  21 +#### Main Documentation Generation Functions
16 22
17 23 # Generate the documentation for a source file by reading it in, splitting it
18   -# up into comment/code sections, highlighting them, and generating the corresponding
19   -# HTML. For the moment, we run a separate **Pygments** process for each section,
20   -# which is quite wasteful. In the future, we should either use a JavaScript-based
21   -# syntax highlighter, or insert section delimiters and run a single **Pygments** process.
  24 +# up into comment/code sections, highlighting them for the appropriate language,
  25 +# and generating the corresponding HTML.
22 26 generate_documentation: (source) ->
23 27 ensure_directory ->
24 28 set_language source
@@ -31,7 +35,10 @@ generate_documentation: (source) ->
31 35
32 36 # Highlights a single chunk of CoffeeScript code, using **Pygments** over stdio,
33 37 # and runs the text of its corresponding comment through **Markdown**, using the
34   -# **Github-flavored-Markdown** modification of **Showdown.js**.
  38 +# **Github-flavored-Markdown** modification of [Showdown.js](http://attacklab.net/showdown/).
  39 +#
  40 +# We process the entire file in a single call to Pygments by inserting little
  41 +# marker comments between each section and then splitting the results.
35 42 highlight: (source, sections, callback) ->
36 43 pygments: process.createChildProcess 'pygmentize', ['-l', language.name, '-f', 'html']
37 44 output: ''
@@ -49,7 +56,8 @@ highlight: (source, sections, callback) ->
49 56 pygments.write((section.code_text for section in sections).join(language.divider_text))
50 57 pygments.close()
51 58
52   -# Parse out each comments and the code that follows into a individual section.
  59 +# Given a string of source code, parse out each comment and the code that
  60 +# follows it into an individual section.
53 61 # Sections take the form:
54 62 #
55 63 # {
@@ -83,8 +91,8 @@ parse: (code) ->
83 91 sections
84 92
85 93 # Once all of the code is finished highlighting, we can generate the HTML file
86   -# and write out the documentation. In the future, it would be nice to extract
87   -# these HTML strings into a template.
  94 +# and write out the documentation. The HTML is generated by running the template
  95 +# found in `resources/docco.jst`, and passing it the completed sections.
88 96 generate_html: (source, sections) ->
89 97 title: path.basename source
90 98 html: docco_template {
@@ -92,37 +100,45 @@ generate_html: (source, sections) ->
92 100 }
93 101 fs.writeFile destination(source), html
94 102
95   -# Helpers
96   -# -------
  103 +#### Helpers & Setup
  104 +
  105 +# Require our external dependencies, including **Showdown.js**
  106 +# (the JavaScript implementation of Markdown).
  107 +require.paths.unshift __dirname
  108 +fs: require 'fs'
  109 +path: require 'path'
  110 +showdown: require('vendor/showdown').Showdown
97 111
98   -# A map of the languages that Docco supports.
99   -# File extension mapped to Pygments name and comment symbol.
  112 +# A list of the languages that Docco supports, mapping the file extension to
  113 +# the name of the Pygments lexer and the symbol that indicates a comment. To
  114 +# add another language to Docco's repertoire, add it here.
100 115 languages: {
101 116 '.coffee': {name: 'coffee-script', symbol: '#'}
102 117 '.js': {name: 'javascript', symbol: '//'}
103 118 '.rb': {name: 'ruby', symbol: '#'}
104 119 }
105 120
106   -# The language of the current sourcefile.
  121 +# The language object, containing the appropriate matchers and delimiters for
  122 +# for the current sourcefile's language.
107 123 language: null
108 124
109   -# Set the current language we're documenting, based on the extension of the
110   -# source file.
  125 +# Set the current language we're documenting, based on the extension.
111 126 set_language: (source) ->
112 127 l: language: languages[path.extname(source)]
113 128
114   - # Does the line begin with a comment? Handle `#` and `//` -style comments.
  129 + # Does the line begin with a comment?
115 130 l.comment_matcher: new RegExp('^\\s*' + l.symbol + '\\s?')
116 131
117   - # The dividing token we feed into Pygments, so that we can get all of the
118   - # sections to be highlighted in a single pass.
  132 + # The dividing token we feed into Pygments, to delimit the boundaries between
  133 + # sections.
119 134 l.divider_text: '\n' + l.symbol + 'DIVIDER\n'
120 135
121   - # The mirror of the divider that Pygments returns, that we split on in order
122   - # to recover the original sections.
  136 + # The mirror of `divider_text` that we expect Pygments to return. We can split
  137 + # on this to recover the original sections.
123 138 l.divider_html: new RegExp('\\n*<span class="c1">' + l.symbol + 'DIVIDER<\\/span>\\n*')
124 139
125   -# Compute the destination HTML path for an input source file.
  140 +# Compute the destination HTML path for an input source file path. If the source
  141 +# is `lib/example.coffee`, the HTML will be at `docs/example.html`
126 142 destination: (filepath) ->
127 143 'docs/' + path.basename(filepath, path.extname(filepath)) + '.html'
128 144
@@ -130,7 +146,7 @@ destination: (filepath) ->
130 146 ensure_directory: (callback) ->
131 147 exec 'mkdir -p docs', -> callback()
132 148
133   -# Micro-templating, borrowed from John Resig, by way of
  149 +# Micro-templating, originally by John Resig, borrowed by way of
134 150 # [Underscore.js](http://documentcloud.github.com/underscore/).
135 151 template: (str) ->
136 152 new Function 'obj',
@@ -145,7 +161,7 @@ template: (str) ->
145 161 .split('%>').join("p.push('") +
146 162 "');}return p.join('');"
147 163
148   -# The template that we use to generate the Docco HTML page.
  164 +# Create the template that we will use to generate the Docco HTML page.
149 165 docco_template: template fs.readFileSync __dirname + '/resources/docco.jst'
150 166
151 167 # The CSS styles we'd like to apply to the documentation.
122 index.html
... ... @@ -0,0 +1,122 @@
  1 +<!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
  2 +documentation generator. It produces HTML that displays your comments
  3 +alongside your code. Comments are passed through
  4 +<a href="http://daringfireball.net/projects/markdown/syntax">Markdown</a>, and code is
  5 +passed through <a href="http://pygments.org/">Pygments</a> syntax highlighting.
  6 +This page is the result of running Docco against its own source file.</p>
  7 +
  8 +<p>If you install Docco, you can run it from the command-line:</p>
  9 +
  10 +<pre><code>docco src/*.coffee
  11 +</code></pre>
  12 +
  13 +<p>...will generate linked HTML documentation for the named source files, saving
  14 +it into a <code>docs</code> folder.</p>
  15 +
  16 +<p>To install Docco, first make sure you have <a href="http://nodejs.org/">Node.js</a> and
  17 +<a href="http://coffeescript.org/">CoffeeScript</a>. Then, to install system-wide in
  18 +<code>/usr/local</code>:</p>
  19 +
  20 +<pre><code>sudo cake install
  21 +</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
  22 +up into comment/code sections, highlighting them for the appropriate language,
  23 +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>
  24 + <span class="nx">ensure_directory</span> <span class="o">-&gt;</span>
  25 + <span class="nx">set_language</span> <span class="nx">source</span>
  26 + <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>
  27 + <span class="k">throw</span> <span class="nx">error</span> <span class="k">if</span> <span class="nx">error</span>
  28 + <span class="nv">sections: </span><span class="nx">parse</span> <span class="nx">code</span>
  29 + <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>
  30 + <span class="nx">generate_html</span> <span class="nx">source</span><span class="p">,</span> <span class="nx">sections</span>
  31 + <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,
  32 +and runs the text of its corresponding comment through <strong>Markdown</strong>, using the
  33 +<strong>Github-flavored-Markdown</strong> modification of <a href="http://attacklab.net/showdown/">Showdown.js</a>.</p>
  34 +
  35 +<p>We process the entire file in a single call to Pygments by inserting little
  36 +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>
  37 + <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>
  38 + <span class="nv">output: </span><span class="s1">&#39;&#39;</span>
  39 + <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>
  40 + <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>
  41 + <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>
  42 + <span class="nx">output</span> <span class="o">+=</span> <span class="nx">result</span> <span class="k">if</span> <span class="nx">result</span>
  43 + <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>
  44 + <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>
  45 + <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>
  46 + <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>
  47 + <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>
  48 + <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>
  49 + <span class="nx">callback</span><span class="p">()</span>
  50 + <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>
  51 + <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
  52 +follows it into an individual section.
  53 +Sections take the form:</p>
  54 +
  55 +<pre><code>{
  56 + docs_text: ...
  57 + docs_html: ...
  58 + code_text: ...
  59 + code_html: ...
  60 +}
  61 +</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>
  62 + <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>
  63 + <span class="nv">sections: </span><span class="p">[]</span>
  64 + <span class="nv">has_code: docs_text: code_text: </span><span class="s1">&#39;&#39;</span>
  65 +
  66 + <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>
  67 + <span class="nx">sections</span><span class="p">.</span><span class="nx">push</span> <span class="p">{</span>
  68 + <span class="nv">docs_text: </span><span class="nx">docs</span>
  69 + <span class="nv">code_text: </span><span class="nx">code</span>
  70 + <span class="p">}</span>
  71 +
  72 + <span class="k">for</span> <span class="nx">line</span> <span class="k">in</span> <span class="nx">lines</span>
  73 + <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>
  74 + <span class="k">if</span> <span class="nx">has_code</span>
  75 + <span class="nx">save</span> <span class="nx">docs_text</span><span class="p">,</span> <span class="nx">code_text</span>
  76 + <span class="nv">has_code: docs_text: code_text: </span><span class="s1">&#39;&#39;</span>
  77 + <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>
  78 + <span class="k">else</span>
  79 + <span class="nv">has_code: </span><span class="kc">true</span>
  80 + <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>
  81 + <span class="nx">save</span> <span class="nx">docs_text</span><span class="p">,</span> <span class="nx">code_text</span>
  82 + <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
  83 +and write out the documentation. The HTML is generated by running the template
  84 +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>
  85 + <span class="nv">title: </span><span class="nx">path</span><span class="p">.</span><span class="nx">basename</span> <span class="nx">source</span>
  86 + <span class="nv">html: </span> <span class="nx">docco_template</span> <span class="p">{</span>
  87 + <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>
  88 + <span class="p">}</span>
  89 + <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>
  90 +(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>
  91 +<span class="nv">fs: </span> <span class="nx">require</span> <span class="s1">&#39;fs&#39;</span>
  92 +<span class="nv">path: </span> <span class="nx">require</span> <span class="s1">&#39;path&#39;</span>
  93 +<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
  94 +the name of the Pygments lexer and the symbol that indicates a comment. To
  95 +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>
  96 + <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>
  97 + <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>
  98 + <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>
  99 +<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
  100 +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>
  101 + <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
  102 +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
  103 +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
  104 +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>
  105 + <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>
  106 + <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
  107 +<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>
  108 + <span class="k">new</span> <span class="nb">Function</span> <span class="s1">&#39;obj&#39;</span><span class="p">,</span>
  109 + <span class="s1">&#39;var p=[],print=function(){p.push.apply(p,arguments);};&#39;</span> <span class="o">+</span>
  110 + <span class="s1">&#39;with(obj){p.push(\&#39;&#39;</span> <span class="o">+</span>
  111 + <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>
  112 + <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>
  113 + <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>
  114 + <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>
  115 + <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>
  116 + <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>
  117 + <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>
  118 + <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.
  119 +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>
  120 +<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>
  121 +
  122 +</pre></div> </td> </tr> </tbody> </table> </div> </body> </html>
16 resources/docco.css
@@ -13,10 +13,10 @@ a {
13 13 color: #261a3b;
14 14 }
15 15 p {
16   - margin: 0;
  16 + margin: 0 0 15px 0;
17 17 }
18   -h1 {
19   - margin: 40px 0 0 0;
  18 +h1, h2, h3, h4, h5, h6 {
  19 + margin: 40px 0 15px 0;
20 20 }
21 21 #jump_to, #jump_page {
22 22 background: white;
@@ -68,7 +68,7 @@ table td {
68 68 max-width: 500px;
69 69 min-width: 500px;
70 70 min-height: 5px;
71   - padding: 10px 30px 16px 50px;
  71 + padding: 10px 30px 1px 50px;
72 72 vertical-align: top;
73 73 text-align: left;
74 74 }
@@ -76,6 +76,12 @@ table td {
76 76 margin: 15px 0 15px;
77 77 padding-left: 15px;
78 78 }
  79 + .docs p tt, .docs p code {
  80 + background: #f8f8ff;
  81 + border: 1px solid #dedede;
  82 + font-size: 12px;
  83 + padding: 0 0.2em;
  84 + }
79 85 .octowrap {
80 86 position: relative;
81 87 }
@@ -99,7 +105,7 @@ table td {
99 105 background: #f5f5ff;
100 106 border-left: 1px solid #e5e5ee;
101 107 }
102   - pre {
  108 + pre, tt, code {
103 109 font-size: 12px; line-height: 18px;
104 110 font-family: Monaco, Consolas, "Lucida Console", monospace;
105 111 margin: 0; padding: 0;

0 comments on commit 9787430

Please sign in to comment.
Something went wrong with that request. Please try again.