Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Docco 0.2.0, with and NPM installer.

  • Loading branch information...
commit 948a172b5bb11450caa73aba969bdded6d75524e 1 parent b2d97bc
Jeremy Ashkenas jashkenas authored
8 Cakefile
... ... @@ -1,7 +1,11 @@
1   -exec = require('child_process').exec
  1 +{spawn, exec} = require 'child_process'
2 2
3 3 option '-p', '--prefix [DIR]', 'set the installation prefix for `cake install`'
4 4
  5 +task 'build', 'build the docco library', ->
  6 + coffee = spawn 'coffee', ['-cw', '-o', 'lib', 'src']
  7 + coffee.stdout.on 'data', (data) -> print data.toString()
  8 +
5 9 task 'install', 'install the `docco` command into /usr/local (or --prefix)', (options) ->
6 10 base = options.prefix or '/usr/local'
7 11 lib = base + '/lib/docco'
@@ -15,7 +19,7 @@ task 'install', 'install the `docco` command into /usr/local (or --prefix)', (op
15 19
16 20 task 'doc', 'rebuild the Docco documentation', ->
17 21 exec([
18   - 'bin/docco docco.coffee'
  22 + 'bin/docco src/docco.coffee'
19 23 'sed "s/docco.css/resources\\/docco.css/" < docs/docco.html > index.html'
20 24 'rm -r docs'
21 25 ].join(' && '), (err) ->
10 bin/docco
... ... @@ -1,10 +1,8 @@
1 1 #!/usr/bin/env node
2 2
3 3 var path = require('path');
4   -var fs = require('fs');
5   -var lib = path.join(path.dirname(fs.realpathSync(__filename)), '../');
6   -var cmd = 'coffee ' + path.join(lib, 'docco.coffee') + ' -- ' + process.ARGV.slice(2).join(' ');
  4 +var fs = require('fs');
  5 +var lib = path.join(path.dirname(fs.realpathSync(__filename)), '../lib');
7 6
8   -require('child_process').exec(cmd, function(err, stdout, stderr) {
9   - if (err) process.stdio.writeError(stderr.read());
10   -});
  7 +process.ARGV = process.argv = process.argv.slice(2, process.argv.length);
  8 +require(lib + '/docco.js');
14 index.html
@@ -16,10 +16,9 @@
16 16 <p>To install Docco, first make sure you have <a href="http://nodejs.org/">Node.js</a>,
17 17 <a href="http://pygments.org/">Pygments</a> (install the latest dev version of Pygments
18 18 from <a href="http://dev.pocoo.org/hg/pygments-main">its Mercurial repo</a>), and
19   -<a href="http://coffeescript.org/">CoffeeScript</a>. Then, to install system-wide in
20   -<code>/usr/local</code>:</p>
  19 +<a href="http://coffeescript.org/">CoffeeScript</a>. Then, with NPM:</p>
21 20
22   -<pre><code>sudo cake install
  21 +<pre><code>sudo npm install docco
23 22 </code></pre>
24 23
25 24 <p>If <strong>Node.js</strong> doesn't run on your platform, or you'd prefer a more convenient
@@ -95,12 +94,13 @@
95 94 <span class="nv">html = </span><span class="nx">docco_template</span> <span class="p">{</span>
96 95 <span class="nx">title</span><span class="o">:</span> <span class="nx">title</span><span class="p">,</span> <span class="nx">sections</span><span class="o">:</span> <span class="nx">sections</span><span class="p">,</span> <span class="nx">sources</span><span class="o">:</span> <span class="nx">sources</span><span class="p">,</span> <span class="nx">path</span><span class="o">:</span> <span class="nx">path</span><span class="p">,</span> <span class="nx">destination</span><span class="o">:</span> <span class="nx">destination</span>
97 96 <span class="p">}</span>
98   - <span class="nx">puts</span> <span class="s2">&quot;docco: $source -&gt; $dest&quot;</span>
  97 + <span class="nx">puts</span> <span class="s2">&quot;docco: #{source} -&gt; #{dest}&quot;</span>
99 98 <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>
100 99 (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>
101 100 <span class="nv">path = </span><span class="nx">require</span> <span class="s1">&#39;path&#39;</span>
102   -<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>
103   -<span class="p">{</span><span class="nx">spawn</span><span class="p">,</span> <span class="nx">exec</span><span class="p">}</span> <span class="o">=</span> <span class="nx">require</span> <span class="s1">&#39;child_process&#39;</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
  101 +<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>
  102 +<span class="p">{</span><span class="nx">spawn</span><span class="p">,</span> <span class="nx">exec</span><span class="p">}</span> <span class="o">=</span> <span class="nx">require</span> <span class="s1">&#39;child_process&#39;</span>
  103 +<span class="p">{</span><span class="nx">puts</span><span class="p">,</span> <span class="nx">print</span><span class="p">}</span> <span class="o">=</span> <span class="nx">require</span> <span class="s1">&#39;sys&#39;</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
104 104 the name of the Pygments lexer and the symbol that indicates a comment. To
105 105 add another language to Docco's repertoire, add it here.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">languages =</span>
106 106 <span class="s1">&#39;.coffee&#39;</span><span class="o">:</span>
@@ -125,7 +125,7 @@
125 125 <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>
126 126 <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>
127 127 <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>
128   - <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="p">(</span><span class="nx">__dirname</span> <span class="o">+</span> <span class="s1">&#39;/resources/docco.jst&#39;</span><span class="p">).</span><span class="nx">toString</span><span class="p">()</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="p">(</span><span class="nx">__dirname</span> <span class="o">+</span> <span class="s1">&#39;/resources/resources/docco.css&#39;</span><span class="p">).</span><span class="nx">toString</span><span class="p">()</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.
  128 + <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="p">(</span><span class="nx">__dirname</span> <span class="o">+</span> <span class="s1">&#39;/../resources/docco.jst&#39;</span><span class="p">).</span><span class="nx">toString</span><span class="p">()</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="p">(</span><span class="nx">__dirname</span> <span class="o">+</span> <span class="s1">&#39;/../resources/resources/docco.css&#39;</span><span class="p">).</span><span class="nx">toString</span><span class="p">()</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.
129 129 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>
130 130 <span class="k">if</span> <span class="nx">sources</span><span class="p">.</span><span class="nx">length</span>
131 131 <span class="nx">ensure_directory</span> <span class="o">-&gt;</span>
160 lib/docco.js
... ... @@ -0,0 +1,160 @@
  1 +(function() {
  2 + var _a, _b, _c, destination, docco_styles, docco_template, ensure_directory, exec, ext, fs, generate_documentation, generate_html, get_language, highlight, highlight_end, highlight_start, l, languages, parse, path, print, puts, showdown, sources, spawn, template;
  3 + var __hasProp = Object.prototype.hasOwnProperty;
  4 + generate_documentation = function(source, callback) {
  5 + return fs.readFile(source, "utf-8", function(error, code) {
  6 + var sections;
  7 + if (error) {
  8 + throw error;
  9 + }
  10 + sections = parse(source, code);
  11 + return highlight(source, sections, function() {
  12 + generate_html(source, sections);
  13 + return callback();
  14 + });
  15 + });
  16 + };
  17 + parse = function(source, code) {
  18 + var _a, _b, _c, code_text, docs_text, has_code, language, line, lines, save, sections;
  19 + lines = code.split('\n');
  20 + sections = [];
  21 + language = get_language(source);
  22 + has_code = (docs_text = (code_text = ''));
  23 + save = function(docs, code) {
  24 + return sections.push({
  25 + docs_text: docs,
  26 + code_text: code
  27 + });
  28 + };
  29 + _b = lines;
  30 + for (_a = 0, _c = _b.length; _a < _c; _a++) {
  31 + line = _b[_a];
  32 + if (line.match(language.comment_matcher)) {
  33 + if (has_code) {
  34 + save(docs_text, code_text);
  35 + has_code = (docs_text = (code_text = ''));
  36 + }
  37 + docs_text += line.replace(language.comment_matcher, '') + '\n';
  38 + } else {
  39 + has_code = true;
  40 + code_text += line + '\n';
  41 + }
  42 + }
  43 + save(docs_text, code_text);
  44 + return sections;
  45 + };
  46 + highlight = function(source, sections, callback) {
  47 + var _a, _b, _c, _d, language, output, pygments, section;
  48 + language = get_language(source);
  49 + pygments = spawn('pygmentize', ['-l', language.name, '-f', 'html', '-O', 'encoding=utf-8']);
  50 + output = '';
  51 + pygments.stderr.addListener('data', function(error) {
  52 + if (error) {
  53 + return puts(error);
  54 + }
  55 + });
  56 + pygments.stdout.addListener('data', function(result) {
  57 + if (result) {
  58 + return output += result;
  59 + }
  60 + });
  61 + pygments.addListener('exit', function() {
  62 + var _a, _b, fragments, i, section;
  63 + output = output.replace(highlight_start, '').replace(highlight_end, '');
  64 + fragments = output.split(language.divider_html);
  65 + _a = sections;
  66 + for (i = 0, _b = _a.length; i < _b; i++) {
  67 + section = _a[i];
  68 + section.code_html = highlight_start + fragments[i] + highlight_end;
  69 + section.docs_html = showdown.makeHtml(section.docs_text);
  70 + }
  71 + return callback();
  72 + });
  73 + pygments.stdin.write((function() {
  74 + _a = []; _c = sections;
  75 + for (_b = 0, _d = _c.length; _b < _d; _b++) {
  76 + section = _c[_b];
  77 + _a.push(section.code_text);
  78 + }
  79 + return _a;
  80 + })().join(language.divider_text));
  81 + return pygments.stdin.end();
  82 + };
  83 + generate_html = function(source, sections) {
  84 + var dest, html, title;
  85 + title = path.basename(source);
  86 + dest = destination(source);
  87 + html = docco_template({
  88 + title: title,
  89 + sections: sections,
  90 + sources: sources,
  91 + path: path,
  92 + destination: destination
  93 + });
  94 + puts("docco: " + (source) + " -> " + (dest));
  95 + return fs.writeFile(dest, html);
  96 + };
  97 + fs = require('fs');
  98 + path = require('path');
  99 + showdown = require('./../vendor/showdown').Showdown;
  100 + _a = require('child_process');
  101 + spawn = _a.spawn;
  102 + exec = _a.exec;
  103 + _b = require('sys');
  104 + puts = _b.puts;
  105 + print = _b.print;
  106 + languages = {
  107 + '.coffee': {
  108 + name: 'coffee-script',
  109 + symbol: '#'
  110 + },
  111 + '.js': {
  112 + name: 'javascript',
  113 + symbol: '//'
  114 + },
  115 + '.rb': {
  116 + name: 'ruby',
  117 + symbol: '#'
  118 + }
  119 + };
  120 + _c = languages;
  121 + for (ext in _c) {
  122 + if (!__hasProp.call(_c, ext)) continue;
  123 + l = _c[ext];
  124 + l.comment_matcher = new RegExp('^\\s*' + l.symbol + '\\s?');
  125 + l.divider_text = '\n' + l.symbol + 'DIVIDER\n';
  126 + l.divider_html = new RegExp('\\n*<span class="c1">' + l.symbol + 'DIVIDER<\\/span>\\n*');
  127 + }
  128 + get_language = function(source) {
  129 + return languages[path.extname(source)];
  130 + };
  131 + destination = function(filepath) {
  132 + return 'docs/' + path.basename(filepath, path.extname(filepath)) + '.html';
  133 + };
  134 + ensure_directory = function(callback) {
  135 + return exec('mkdir -p docs', function() {
  136 + return callback();
  137 + });
  138 + };
  139 + template = function(str) {
  140 + return new Function('obj', 'var p=[],print=function(){p.push.apply(p,arguments);};' + 'with(obj){p.push(\'' + str.replace(/[\r\t\n]/g, " ").replace(/'(?=[^<]*%>)/g, "\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g, "',$1,'").split('<%').join("');").split('%>').join("p.push('") + "');}return p.join('');");
  141 + };
  142 + docco_template = template(fs.readFileSync(__dirname + '/../resources/docco.jst').toString());
  143 + docco_styles = fs.readFileSync(__dirname + '/../resources/docco.css').toString();
  144 + highlight_start = '<div class="highlight"><pre>';
  145 + highlight_end = '</pre></div>';
  146 + sources = process.ARGV.sort();
  147 + if (sources.length) {
  148 + ensure_directory(function() {
  149 + var files, next_file;
  150 + fs.writeFile('docs/docco.css', docco_styles);
  151 + files = sources.slice(0);
  152 + next_file = function() {
  153 + if (files.length) {
  154 + return generate_documentation(files.shift(), next_file);
  155 + }
  156 + };
  157 + return next_file();
  158 + });
  159 + }
  160 +})();
21 package.json
... ... @@ -0,0 +1,21 @@
  1 +{
  2 + "name": "docco",
  3 + "description": "The Quick and Dirty Literate Programming Documentation Generator",
  4 + "keywords": ["documentation", "docs", "generator", "coffeescript"],
  5 + "author": "Jeremy Ashkenas",
  6 + "version": "0.2.0",
  7 + "licenses": [{
  8 + "type": "MIT",
  9 + "url": "http://opensource.org/licenses/mit-license.php"
  10 + }],
  11 + "engines": {
  12 + "node": ">=0.2.0"
  13 + },
  14 + "directories": {
  15 + "lib" : "./lib"
  16 + },
  17 + "main" : "./lib/docco",
  18 + "bin": {
  19 + "docco": "./bin/docco",
  20 + }
  21 +}
14 docco.coffee → src/docco.coffee
@@ -15,10 +15,9 @@
15 15 # To install Docco, first make sure you have [Node.js](http://nodejs.org/),
16 16 # [Pygments](http://pygments.org/) (install the latest dev version of Pygments
17 17 # from [its Mercurial repo](http://dev.pocoo.org/hg/pygments-main)), and
18   -# [CoffeeScript](http://coffeescript.org/). Then, to install system-wide in
19   -# `/usr/local`:
  18 +# [CoffeeScript](http://coffeescript.org/). Then, with NPM:
20 19 #
21   -# sudo cake install
  20 +# sudo npm install docco
22 21 #
23 22 # If **Node.js** doesn't run on your platform, or you'd prefer a more convenient
24 23 # package, get [Rocco](http://rtomayko.github.com/rocco/), the Ruby port that's
@@ -107,7 +106,7 @@ generate_html = (source, sections) ->
107 106 html = docco_template {
108 107 title: title, sections: sections, sources: sources, path: path, destination: destination
109 108 }
110   - puts "docco: $source -> $dest"
  109 + puts "docco: #{source} -> #{dest}"
111 110 fs.writeFile dest, html
112 111
113 112 #### Helpers & Setup
@@ -116,8 +115,9 @@ generate_html = (source, sections) ->
116 115 # (the JavaScript implementation of Markdown).
117 116 fs = require 'fs'
118 117 path = require 'path'
119   -showdown = require('./vendor/showdown').Showdown
  118 +showdown = require('./../vendor/showdown').Showdown
120 119 {spawn, exec} = require 'child_process'
  120 +{puts, print} = require 'sys'
121 121
122 122 # A list of the languages that Docco supports, mapping the file extension to
123 123 # the name of the Pygments lexer and the symbol that indicates a comment. To
@@ -172,10 +172,10 @@ template = (str) ->
172 172 "');}return p.join('');"
173 173
174 174 # Create the template that we will use to generate the Docco HTML page.
175   -docco_template = template fs.readFileSync(__dirname + '/resources/docco.jst').toString()
  175 +docco_template = template fs.readFileSync(__dirname + '/../resources/docco.jst').toString()
176 176
177 177 # The CSS styles we'd like to apply to the documentation.
178   -docco_styles = fs.readFileSync(__dirname + '/resources/docco.css').toString()
  178 +docco_styles = fs.readFileSync(__dirname + '/../resources/docco.css').toString()
179 179
180 180 # The start of each Pygments highlight block.
181 181 highlight_start = '<div class="highlight"><pre>'

0 comments on commit 948a172

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