gulp-jsdoc
Version:
A jsdoc plugin for Gulp
332 lines (204 loc) • 9.22 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>gulp-jsdoc Index</title>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
<link type="text/css" rel="stylesheet" href="styles/site.journal.css">
</head>
<body>
<div class="container-fluid">
<div class="navbar navbar-fixed-top ">
<div class="navbar-inner">
<a class="brand" href="index.html">gulp-jsdoc</a>
<ul class="nav">
</ul>
</div>
</div>
<div class="row-fluid">
<div class="span8">
<div id="main">
<span class="page-title">Index</span>
<section>
<article><h1 id="gulp-jsdoc">gulp-jsdoc</h1>
<p><a href="https://npmjs.org/package/gulp-jsdoc"><img src="https://badge.fury.io/js/gulp-jsdoc.png" alt="NPM version"></a> <a href="http://travis-ci.org/jsBoot/gulp-jsdoc"><img src="https://secure.travis-ci.org/jsBoot/gulp-jsdoc.png?branch=master" alt="Build Status"></a> <a href="https://coveralls.io/r/jsBoot/gulp-jsdoc"><img src="https://coveralls.io/repos/jsBoot/gulp-jsdoc/badge.png?branch=master" alt="Coverage Status"></a> <a href="https://david-dm.org/jsBoot/gulp-jsdoc"><img src="https://david-dm.org/jsBoot/gulp-jsdoc.png" alt="Dependency Status"></a></p>
<blockquote>
<p>jsdoc plugin for <a href="https://github.com/wearefractal/gulp">gulp</a></p>
</blockquote>
<h2 id="warning">WARNING</h2>
<p>This is an early release - if you find bugs, please say so.</p>
<p>Also, the following are currently not supported:</p>
<ul>
<li>plugins</li>
<li>tutorials</li>
<li>configuration from jsdoc.conf files</li>
</ul>
<p>If you have a use-case that you can't do with straight gulp in a better way, please say so.</p>
<h2 id="tl-dr">TL;DR</h2>
<p>Install <code>gulp-jsdoc</code> as a development dependency:</p>
<pre><code class="lang-shell">npm install --save-dev gulp-jsdoc
</code></pre>
<p>Then, add it to your <code>gulpfile.js</code>:</p>
<pre><code class="lang-javascript">var jsdoc = require("gulp-jsdoc");
gulp.src("./src/*.js")
.pipe(jsdoc('./documentation-output'))
</code></pre>
<h2 id="api">API</h2>
<h3 id="jsdoc-parser-infos-name-">jsdoc.parser(infos, name)</h3>
<pre><code class="lang-javascript">gulp.src("./src/*.js")
.pipe(jsdoc.parser(infos, name))
.pipe(dest('./somewhere'))
</code></pre>
<p>Will process any files it has been fed, and generate a new vinyl JSON usable by the generator to produce actual documentation.</p>
<p>By default, the filename is 'jsdoc.json' unless overriden by the name parameter.</p>
<p>Note that if you feed the parser a README.md file, this file will be rendered and used as a long description for your package.</p>
<p>eg:</p>
<pre><code class="lang-javascript">gulp.src(["./src/*.js", "README.md"])
.pipe(jsdoc.parser(infos, name))
.pipe(dest('./somewhere'))
</code></pre>
<p>The optional infos parameter is fed to jsdoc.</p>
<h4 id="infos-name">infos.name</h4>
<p>Type: <code>String</code><br>Default: <code>''</code></p>
<h4 id="infos-description">infos.description</h4>
<p>Type: <code>String</code><br>Default: <code>''</code></p>
<h4 id="infos-version">infos.version</h4>
<p>Type: <code>String</code><br>Default: <code>''</code></p>
<h4 id="infos-licenses">infos.licenses</h4>
<p>Type: <code>Array</code><br>Default: <code>[]</code></p>
<h3 id="jsdoc-generator-destination-template-options-">jsdoc.generator(destination, template, options)</h3>
<pre><code class="lang-javascript">gulp.src("./somewhere/jsdoc.json")
.pipe(jsdoc.generator('./destination'))
</code></pre>
<p>or directly from the parser pipe:</p>
<pre><code class="lang-javascript">gulp.src(["./src/*.js", "README.md"])
.pipe(jsdoc.parser(infos, name))
.pipe(jsdoc.generator('./destination'))
</code></pre>
<p>By default, the generator uses the default template.</p>
<h4 id="destination">destination</h4>
<p>Type: <code>String</code><br>Default: <code>''</code></p>
<p>Where the documentation will be outputed.
If an infos object with a version / name was provided to the parser, these will be used in the final path.</p>
<h4 id="template">template</h4>
<p>You may optionnally specify a custom template, using the following syntax</p>
<pre><code>{
path: 'path_to_template',
anyTemplateSpecificParameter: 'whatever'
}
</code></pre><p>As a courtesy, gulp-jsdoc bundles ink-docstrap templates, that you may use directly this way:</p>
<pre><code>{
path: 'ink-docstrap',
systemName : 'Something'',
footer : "Something",
copyright : "Something",
navType : "vertical",
theme : "journal",
linenums : true,
collapseSymbols : false,
inverseNav : false
}
</code></pre><p>See <a href="https://github.com/terryweiss/docstrap">their site</a> for more infos.</p>
<h4 id="options">options</h4>
<p>You may optionnally override default jsdoc behavior with this object:</p>
<pre><code> {
'private': false,
monospaceLinks: false,
cleverLinks: false,
outputSourceFiles: true
}
</code></pre><h3 id="jsdoc-destination-template-infos-options-">jsdoc(destination, template, infos, options)</h3>
<pre><code class="lang-javascript">gulp.src(["./src/*.js", "README.md"])
.pipe(jsdoc('./destination'))
</code></pre>
<p>... is simply a shortcut for</p>
<pre><code class="lang-javascript">gulp.src(["./src/*.js", "README.md"])
.pipe(jsdoc.parser())
.pipe(jsdoc.generator('./destination'))
</code></pre>
<h2 id="limitations">Limitations</h2>
<p>Only the parser is really using streams. While the generator will read from the result of the parser, it will also read and write templates files on its own.</p>
<p>There is nothing we can do about that, unless changing the jsdoc templating API entirely, and all existing templates...</p>
<h2 id="license">License</h2>
<p><a href="http://en.wikipedia.org/wiki/MIT_License">MIT License</a></p>
</article>
</section>
<h1 class="page-title">Index</h1>
<section>
<header>
<h2>
parser.js
</h2>
</header>
<article>
<div class="container-overview">
<div class="description">Parser</div>
<dl class="details">
<dt class="tag-version">Version:</dt>
<dd class="tag-version"><ul class="dummy"><li>0.0.0</li></ul></dd>
<dt class="tag-author">Author:</dt>
<dd class="tag-author">
<ul>
<li>Mangled Deutz</li>
</ul>
</dd>
<dt class="tag-copyright">Copyright:</dt>
<dd class="tag-copyright"><ul class="dummy"><li>Mangled Deutz</li></ul></dd>
<dt class="tag-license">License:</dt>
<dd class="tag-license"><ul class="dummy"><li>MIT.</li></ul></dd>
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="parser.js.html">parser.js</a>, <a href="parser.js.html#sunlight-1-line-1">line 1</a>
</li></ul></dd>
</dl>
</div>
</article>
</section>
</div>
<div class="clearfix"></div>
<footer>
Generated with gulp
<br />
<span class="copyright">
Copyright WebItUp 2014
</span>
<br />
<span class="jsdoc-message">
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.0-alpha4</a>
on Wed Feb 05 2014 18:14:42 GMT+0100 (CET) using the <a href="https://github.com/terryweiss/docstrap">DocStrap template</a>.
</span>
</footer>
</div>
<div class="span3">
<div id="toc"></div>
</div>
<br clear="both">
</div>
</div>
<script src="scripts/sunlight.js"></script>
<script src="scripts/sunlight.javascript.js"></script>
<script src="scripts/sunlight-plugin.doclinks.js"></script>
<script src="scripts/sunlight-plugin.linenumbers.js"></script>
<script src="scripts/sunlight-plugin.menu.js"></script>
<script src="scripts/jquery.min.js"></script>
<script src="scripts/jquery.scrollTo.js"></script>
<script src="scripts/jquery.localScroll.js"></script>
<script src="scripts/bootstrap-dropdown.js"></script>
<script src="scripts/toc.js"></script>
<script> Sunlight.highlightAll({lineNumbers:true, showMenu: true, enableDoclinks :true}); </script>
<script>
$( function () {
$( "#toc" ).toc( {
selectors : "h1,h2,h3,h4",
showAndHide : false,
scrollTo : 60
} );
$( "#toc>ul" ).addClass( "nav nav-pills nav-stacked" );
$( "#main span[id^='toc']" ).addClass( "toc-shim" );
} );
</script>
</body>
</html>