Browse files

Docco 0.1.2, for the new Node.

  • Loading branch information...
1 parent 98cb2f7 commit 082a5031c13128e06b2b3ca7a40193cc9274516f @jashkenas committed May 6, 2010
Showing with 17 additions and 17 deletions.
  1. +3 −3 docco.coffee
  2. +14 −14 index.html
View
6 docco.coffee
@@ -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
28 index.html
@@ -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.
@TBD
TBD added a note May 7, 2010

URL problem, double href

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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.