dokker
Version:
Dokker.js creates professional Javascript code documentations.
498 lines (384 loc) • 27.7 kB
HTML
<html>
<head>
<title>dokker.js</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
<link rel="stylesheet" media="all" href="docco.css" />
</head>
<body>
<div id="container">
<div id="background"></div>
<ul class="sections">
<li id="title">
<div class="annotation">
<h1>dokker.js</h1>
</div>
</li>
<li id="section-1">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-1">¶</a>
</div>
<pre><code>Dokker.js <span class="hljs-number">0.0</span>.1
http:<span class="hljs-comment">//dokker.oceanhouse21.com</span>
(c) <span class="hljs-number">2014</span>-<span class="hljs-number">2015</span> Georg Schlenkhoff and Oceanhouse21
Dokker.js may be freely distributed under the MIT license.
</code></pre>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-pi">
'use strict'</span>;</pre></div></div>
</li>
<li id="section-2">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-2">¶</a>
</div>
<p>Define required dependencies</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-keyword">var</span> <span class="hljs-built_in">Promise</span> = <span class="hljs-built_in">require</span>(<span class="hljs-string">'promise'</span>);
<span class="hljs-keyword">var</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
<span class="hljs-keyword">var</span> path = <span class="hljs-built_in">require</span>(<span class="hljs-string">'path'</span>);
<span class="hljs-keyword">var</span> read = <span class="hljs-built_in">Promise</span>.denodeify(fs.readFile);
<span class="hljs-keyword">var</span> write = <span class="hljs-built_in">Promise</span>.denodeify(fs.writeFile);
<span class="hljs-keyword">var</span> docco = <span class="hljs-built_in">require</span>(<span class="hljs-string">'docco'</span>);
<span class="hljs-keyword">var</span> docdown = <span class="hljs-built_in">require</span>(<span class="hljs-string">'docdown'</span>);
<span class="hljs-keyword">var</span> marked = <span class="hljs-built_in">require</span>(<span class="hljs-string">'marked'</span>);
<span class="hljs-keyword">var</span> ejs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'ejs'</span>);
<span class="hljs-keyword">var</span> cheerio = <span class="hljs-built_in">require</span>(<span class="hljs-string">'cheerio'</span>);
<span class="hljs-keyword">var</span> exec = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>).exec;
<span class="hljs-keyword">var</span> Dokker = {};
Dokker.VERSION = <span class="hljs-string">'0.1.2'</span>;</pre></div></div>
</li>
<li id="section-3">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-3">¶</a>
</div>
<p>Transclude in a ejs template file the HTML snippet that was ultimately
created with docdown. Also tweak the HTML page a bit and finally
inject the README.md.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.injectTemplate = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
<span class="hljs-keyword">var</span> template, body, html, readme, $;
<span class="hljs-keyword">return</span> read(options.template, <span class="hljs-string">'utf8'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
template = data;
<span class="hljs-keyword">return</span> read(options.readme, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
readme = marked(data);
$ = cheerio.load(readme);
$(<span class="hljs-string">'h1'</span>).remove();
readme = $.html();
<span class="hljs-keyword">return</span> read(options.html, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
$ = cheerio.load(data);
<span class="hljs-keyword">return</span> ejs.render(template, {
apiToc: $(<span class="hljs-string">'.toc-container'</span>).html(),
readme: readme,
apiDoc: $(<span class="hljs-string">'.doc-container'</span>).html(),</pre></div></div>
</li>
<li id="section-4">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-4">¶</a>
</div>
<p>correctly setting links to your github/pages</p>
</div>
<div class="content"><div class='highlight'><pre> page_url: options.site,
title: options.title,
github_url: options.github,</pre></div></div>
</li>
<li id="section-5">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-5">¶</a>
</div>
<p>fixed reference to generated annotation
the ‘literate’ in .dokker.json shall not require a source since it’s never used.</p>
</div>
<div class="content"><div class='highlight'><pre> annotated_path: <span class="hljs-string">'annotated/'</span>+options.source
});
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
<span class="hljs-keyword">return</span> write(options.html, data, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
resolve();
}).then(<span class="hljs-literal">null</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
reject(err);
});
});
};</pre></div></div>
</li>
<li id="section-6">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-6">¶</a>
</div>
<p>Create a HTML site from any mocha tests find when executing mocha
—reporter doc terminal command.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.createTests = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
<span class="hljs-keyword">var</span> template, tests;</pre></div></div>
</li>
<li id="section-7">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-7">¶</a>
</div>
<p>allows specification of mocha.command in .dokker.json, e.g. ‘mocha -u tdd —reporter doc’</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">var</span> cmd = options.command || <span class="hljs-string">'mocha --reporter doc'</span>;
exec(cmd, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error, stdout</span>) </span>{
<span class="hljs-keyword">if</span>(error) <span class="hljs-keyword">return</span> reject(error);
tests = stdout;
<span class="hljs-keyword">return</span> read(options.template, <span class="hljs-string">'utf8'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
template = data;
<span class="hljs-keyword">return</span> ejs.render(template, {tests: tests});
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
<span class="hljs-keyword">return</span> write(options.path, data, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
resolve();
}).then(<span class="hljs-literal">null</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
reject(err);
});
});
});
};</pre></div></div>
</li>
<li id="section-8">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-8">¶</a>
</div>
<p>Extract docs folder to separate git branch and finally push branch to
Github repository</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.ghPages = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>)</span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
exec(<span class="hljs-string">'git subtree split -P docs -b gh-pages'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error, stdout, stderr</span>) </span>{
<span class="hljs-keyword">if</span>(error) <span class="hljs-keyword">return</span> reject(stderr);
exec(<span class="hljs-string">'git push origin gh-pages'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error, stdout, stderr</span>) </span>{
<span class="hljs-keyword">if</span>(error) <span class="hljs-keyword">return</span> reject(stderr);
resolve();
});
});
});
};</pre></div></div>
</li>
<li id="section-9">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-9">¶</a>
</div>
<p>Create an HTML file from any source code comments in the style of
<a href="https://de.wikipedia.org/wiki/Literate_programming">literate programming</a></p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.literate = <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
<span class="hljs-keyword">var</span> tmpDir = path.join(process.cwd(), <span class="hljs-string">'/.tmp'</span>);
<span class="hljs-keyword">var</span> tmpFile = path.join(tmpDir, options.source);
<span class="hljs-keyword">return</span> read(path.join(process.cwd(), options.source), <span class="hljs-string">'utf8'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
<span class="hljs-keyword">var</span> source = data.replace(<span class="hljs-regexp">/^\s*(\*|\/\*).*[\r\n]/gm</span>, <span class="hljs-string">''</span>);
<span class="hljs-keyword">return</span> Dokker.mkdir(tmpDir)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">return</span> write(tmpFile, source, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>)</span>{
docco.run([<span class="hljs-string">''</span>, <span class="hljs-string">''</span>, tmpFile, <span class="hljs-string">'-o'</span>, options.dir]);
resolve();
});
}).then(<span class="hljs-literal">null</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> reject(err);
});
});
};</pre></div></div>
</li>
<li id="section-10">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-10">¶</a>
</div>
<p>Convert markdown from any source code comments with docdown module.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.jsdocMarkdown = <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
<span class="hljs-keyword">var</span> source, tmpFile, tmpDir;
<span class="hljs-keyword">return</span> read(path.join(process.cwd(), options.source), <span class="hljs-string">'utf8'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>)</span>{
source = data.replace(<span class="hljs-regexp">/^\s*(\/\/).*[\r\n]/gm</span>, <span class="hljs-string">''</span>);
tmpDir = path.join(process.cwd(), <span class="hljs-string">'/.tmp'</span>);
<span class="hljs-keyword">return</span> Dokker.mkdir(tmpDir);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>)</span>{
tmpFile = path.join(tmpDir, options.source);
<span class="hljs-keyword">return</span> write(tmpFile, source, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>)</span>{
<span class="hljs-keyword">var</span> markdown = docdown({
<span class="hljs-string">'path'</span>: tmpFile,
<span class="hljs-string">'url'</span>: options.github,
<span class="hljs-string">'toc'</span>: <span class="hljs-string">'categories'</span>
});
<span class="hljs-keyword">return</span> write(options.markdown, markdown, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
resolve();
}).then(<span class="hljs-literal">null</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
reject(err);
});
});
};</pre></div></div>
</li>
<li id="section-11">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-11">¶</a>
</div>
<p>Create an HTML file from any source code comments in the style of
<a href="https://de.wikipedia.org/wiki/Literate_programming">literate programming</a></p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.jsdocHtml = <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
<span class="hljs-keyword">return</span> read(options.markdown, <span class="hljs-string">'utf8'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
<span class="hljs-keyword">var</span> html = marked(data).replace(<span class="hljs-regexp">/<!-- /g</span>,<span class="hljs-string">'<'</span>).replace(<span class="hljs-regexp">/ -->/g</span>,<span class="hljs-string">'>'</span>);
<span class="hljs-keyword">return</span> write(options.html, html, <span class="hljs-string">'utf8'</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
resolve();
}).then(<span class="hljs-literal">null</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
reject(err);
});
});
};</pre></div></div>
</li>
<li id="section-12">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-12">¶</a>
</div>
<p>Internal helper function that creates any directory if not existing.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.mkdir = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">dir</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
fs.exists(dir, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">exists</span>) </span>{
<span class="hljs-keyword">if</span> (exists) {
resolve();
} <span class="hljs-keyword">else</span> {
fs.mkdir(dir, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> reject(err);
resolve();
});
}
});
});
};</pre></div></div>
</li>
<li id="section-13">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-13">¶</a>
</div>
<p>Parses the options file, .Dokker.json, and sets the default parameters.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.configure = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>)</span>{
<span class="hljs-keyword">var</span> file = path.join(process.cwd(), <span class="hljs-string">'.dokker.json'</span>);
<span class="hljs-keyword">return</span> read(file, <span class="hljs-string">'utf8'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
data = <span class="hljs-built_in">JSON</span>.parse(data);
data.jsdoc.template = (data.jsdoc.template) ? path.join(process.cwd(), data.jsdoc.template) : path.join(__dirname, <span class="hljs-string">'templates/index.ejs.html'</span>);
data.mocha.template = (data.mocha.template) ? path.join(process.cwd(), data.mocha.template) : path.join(__dirname, <span class="hljs-string">'templates/tests.ejs.html'</span>);
data.mocha.path = path.join(process.cwd(), data.dir, data.mocha.path);</pre></div></div>
</li>
<li id="section-14">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-14">¶</a>
</div>
<p>mocha.command commented out to fix build-breaking bug
specifies mocha command in .dokker.json; e.g. mocha -u tdd -R spec
data.mocha.command = path.join(process.cwd(), data.dir, data.mocha.command);</p>
</div>
<div class="content"><div class='highlight'><pre> data.literate.dir = path.join(process.cwd(), data.dir, data.literate.dir);
data.jsdoc.markdown = path.join(process.cwd(), data.dir, data.jsdoc.markdown);
data.jsdoc.html = path.join(process.cwd(), data.dir, data.jsdoc.html);
data.jsdoc.readme = path.join(process.cwd(), data.jsdoc.readme);
resolve(data);
}).then(<span class="hljs-literal">null</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
reject(err);
});
});
};</pre></div></div>
</li>
<li id="section-15">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-15">¶</a>
</div>
<p>Copy starter template to bootstrap any Dokker project.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.copyTemplate = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
<span class="hljs-keyword">var</span> templatesDir = path.join(process.cwd(), <span class="hljs-string">'templates'</span>);
<span class="hljs-keyword">return</span> Dokker.mkdir(templatesDir)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">var</span> oldStyle = path.join(__dirname, <span class="hljs-string">'templates'</span>, <span class="hljs-string">'styles.css'</span>);
<span class="hljs-keyword">var</span> newStyle = path.join(process.cwd(), options.dir, <span class="hljs-string">'styles.css'</span>);
fs.createReadStream(oldStyle).pipe(fs.createWriteStream(newStyle));
<span class="hljs-keyword">var</span> oldLogo = path.join(__dirname, <span class="hljs-string">'templates'</span>, <span class="hljs-string">'logo.png'</span>);
<span class="hljs-keyword">var</span> newLogo = path.join(process.cwd(), options.dir, <span class="hljs-string">'logo.png'</span>);
fs.createReadStream(oldLogo).pipe(fs.createWriteStream(newLogo));
<span class="hljs-keyword">var</span> oldApp = path.join(__dirname, <span class="hljs-string">'templates'</span>, <span class="hljs-string">'app.js'</span>);
<span class="hljs-keyword">var</span> newApp = path.join(process.cwd(), options.dir, <span class="hljs-string">'app.js'</span>);
fs.createReadStream(oldApp).pipe(fs.createWriteStream(newApp));
resolve();
});
});
};</pre></div></div>
</li>
<li id="section-16">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-16">¶</a>
</div>
<p>Copies the .Dokker.json file to bootstrap any Dokker project.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.init = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>)</span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resolve, reject</span>) </span>{
<span class="hljs-keyword">var</span> oldDok = path.join(__dirname, <span class="hljs-string">'.dokker.json'</span>);
<span class="hljs-keyword">var</span> newDok = path.join(process.cwd(), <span class="hljs-string">'.dokker.json'</span>);
fs.createReadStream(oldDok).pipe(fs.createWriteStream(newDok));
resolve();
});
};</pre></div></div>
</li>
<li id="section-17">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-17">¶</a>
</div>
<p>Starts the Node.js/Express server to watch Dokker.js project
documentation.</p>
</div>
<div class="content"><div class='highlight'><pre>Dokker.watch = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">options</span>) </span>{
<span class="hljs-keyword">var</span> gulpex = <span class="hljs-built_in">require</span>(__dirname + <span class="hljs-string">'/gulpfile.js'</span>).gulpex;
<span class="hljs-keyword">return</span> gulpex();</pre></div></div>
</li>
<li id="section-18">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-18">¶</a>
</div>
<p>return new Promise(function(resolve, reject){
exec(‘DIR=’+ options.dir + ‘ node ‘ + options.dir + ‘/app.js’, function(error, stdout, stderr){
if(error) return reject(stderr);
});
});</p>
</div>
<div class="content"><div class='highlight'><pre>};
<span class="hljs-built_in">module</span>.exports = Dokker;</pre></div></div>
</li>
</ul>
</div>
</body>
</html>