Permalink
Browse files

Docco 0.1.2, for the new Node.

  • Loading branch information...
1 parent 98cb2f7 commit 082a5031c13128e06b2b3ca7a40193cc9274516f @jashkenas jashkenas committed May 7, 2010
Showing with 17 additions and 17 deletions.
  1. +3 −3 docco.coffee
  2. +14 −14 index.html
View
@@ -12,9 +12,9 @@
# ...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`:
+# To install Docco, first make sure you have [Node.js](http://nodejs.org/),
+# [Pygments](http://pygments.org/), and [CoffeeScript](http://coffeescript.org/).
+# Then, to install system-wide in `/usr/local`:
#
# sudo cake install
#
View
@@ -2,7 +2,7 @@
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.
+passed through <a href="<a href='http://pygments.org/'>http://pygments.org/</a>">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>
@@ -13,15 +13,15 @@
<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>
+<p>To install Docco, first make sure you have <a href="<a href='http://nodejs.org/'>http://nodejs.org/</a>">Node.js</a>,
+<a href="<a href='http://pygments.org/'>http://pygments.org/</a>">Pygments</a>, and <a href="<a href='http://coffeescript.org/'>http://coffeescript.org/</a>">CoffeeScript</a>.
+Then, to install system-wide in <code>/usr/local</code>:</p>
<pre><code>sudo cake install
</code></pre>
<p>If <strong>Node.js</strong> doesn't run on your platform, or you'd prefer a more convenient
-package, get <a href="http://rtomayko.github.com/rocco/">Rocco</a>, the Ruby port that's
+package, get <a href="<a href='http://rtomayko.github.com/rocco/'>http://rtomayko.github.com/rocco/</a>">Rocco</a>, the Ruby port that's
available as a gem.</p> </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 merging them into an HTML template.</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="nx">callback</span><span class="p">)</span> <span class="o">-&gt;</span>
@@ -70,11 +70,11 @@
marker comments between each section and then splitting the result string
wherever our markers occur.</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">language: </span><span class="nx">get_language</span> <span class="nx">source</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">pygments: </span><span class="nx">spawn</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">pygments</span><span class="p">.</span><span class="nx">stderr</span><span class="p">.</span><span class="nx">addListener</span> <span class="s1">&#39;data&#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">puts</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">stdout</span><span class="p">.</span><span class="nx">addListener</span> <span class="s1">&#39;data&#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>
@@ -83,8 +83,8 @@
<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-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
+ <span class="nx">pygments</span><span class="p">.</span><span class="nx">stdin</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">stdin</span><span class="p">.</span><span class="nx">end</span><span class="p">()</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. Pass the completed sections into the template
found in <code>resources/docco.jst</code></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>
@@ -94,10 +94,10 @@
<span class="p">}</span>
<span class="nx">puts</span> <span class="s2">&quot;docco: $source -&gt; $dest&quot;</span>
<span class="nx">fs</span><span class="p">.</span><span class="nx">writeFile</span> <span class="nx">dest</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>
+(the JavaScript implementation of Markdown).</p> </td> <td class="code"> <div class="highlight"><pre><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
+<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>
+<span class="p">{</span><span class="nv">spawn: </span><span class="nx">spawn</span><span class="p">,</span> <span class="nv">exec: </span><span class="nx">exec</span><span class="p">}</span><span class="o">:</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;child_process&#39;</span><span class="p">)</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>

0 comments on commit 082a503

Please sign in to comment.