ashatora/openlayers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update JSDoc to get async publish support

Browse Source
This commit is contained in:
Tim Schaub
2015-09-23 09:42:11 -06:00
parent c0da5ff8ef
commit 85ca4e1888
5 changed files with 70 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
config/jsdoc/api/conf.json
+1 -1
View File
@@ -16,7 +16,7 @@
]
},
"plugins": [
"node_modules/jsdoc/plugins/markdown",
"node_modules/jsdoc-fork/plugins/markdown",
"config/jsdoc/api/plugins/inheritdoc",
"config/jsdoc/api/plugins/typedefs",
"config/jsdoc/api/plugins/events",
config/jsdoc/api/plugins/api.js
+1 -1
View File
@@ -16,7 +16,7 @@ exports.defineTags = function(dictionary) {
doclet.stability = level;
} else {
var errorText = util.format('Invalid stability level (%s) in %s line %s', tag.text, doclet.meta.filename, doclet.meta.lineno);
require('jsdoc/util/error').handle( new Error(errorText) );
require('jsdoc-fork/lib/jsdoc/util/error').handle( new Error(errorText) );
}
}
});
config/jsdoc/api/template/publish.js
+37 -37
View File
@@ -1,10 +1,10 @@
/*global env: true */
var template = require('jsdoc/template'),
fs = require('jsdoc/fs'),
path = require('jsdoc/path'),
var template = require('jsdoc-fork/lib/jsdoc/template'),
fs = require('jsdoc-fork/lib/jsdoc/fs'),
path = require('jsdoc-fork/lib/jsdoc/path'),
taffy = require('taffydb').taffy,
handle = require('jsdoc/util/error').handle,
helper = require('jsdoc/util/templateHelper'),
handle = require('jsdoc-fork/lib/jsdoc/util/error').handle,
helper = require('jsdoc-fork/lib/jsdoc/util/templateHelper'),
_ = require('underscore'),
htmlsafe = helper.htmlsafe,
linkto = helper.linkto,
@@ -29,9 +29,9 @@ function getAncestorLinks(doclet) {
function hashToLink(doclet, hash) {
if ( !/^(#.+)/.test(hash) ) { return hash; }
var url = helper.createLink(doclet);
url = url.replace(/(#.+|$)/, hash);
return '<a href="' + url + '">' + hash + '</a>';
}
@@ -59,15 +59,15 @@ function needsSignature(doclet) {
function addSignatureParams(f) {
var params = helper.getSignatureParams(f, 'optional');
f.signature = (f.signature || '') + '('+params.join(', ')+')';
}
function addSignatureReturns(f) {
var returnTypes = helper.getSignatureReturns(f);
f.signature = '<span class="signature">'+(f.signature || '') + '</span>';
if (returnTypes.length) {
f.signature += '<span class="glyphicon glyphicon-circle-arrow-right"></span><span class="type-signature returnType">'+(returnTypes.length ? '{'+returnTypes.join('|')+'}' : '')+'</span>';
}
@@ -75,7 +75,7 @@ function addSignatureReturns(f) {
function addSignatureTypes(f) {
var types = helper.getSignatureTypes(f);
f.signature = (f.signature || '') + '<span class="type-signature">'+(types.length? ' :'+types.join('|') : '')+' </span>';
}
@@ -106,7 +106,7 @@ function getPathFromDoclet(doclet) {
return filepath;
}
function generate(title, docs, filename, resolveLinks) {
resolveLinks = resolveLinks === false ? false : true;
@@ -115,14 +115,14 @@ function generate(title, docs, filename, resolveLinks) {
title: title,
docs: docs
};
var outpath = path.join(outdir, filename),
html = view.render('container.tmpl', docData);
if (resolveLinks) {
html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
}
fs.writeFileSync(outpath, html, 'utf8');
}
@@ -153,7 +153,7 @@ function generateSourceFiles(sourceFiles) {
* exports only that class or function), then attach the classes or functions to the `module`
* property of the appropriate module doclets. The name of each class or function is also updated
* for display purposes. This function mutates the original arrays.
*
*
* @private
* @param {Array.<module:jsdoc/doclet.Doclet>} doclets - The array of classes and functions to
* check.
@@ -268,7 +268,7 @@ exports.publish = function(taffyData, opts, tutorials) {
var templatePath = opts.template;
view = new template.Template(templatePath + '/tmpl');
// claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness
// doesn't try to hand them out later
var indexUrl = helper.getUniqueFilename('index');
@@ -291,16 +291,16 @@ exports.publish = function(taffyData, opts, tutorials) {
var sourceFilePaths = [];
data().each(function(doclet) {
doclet.attribs = '';
if (doclet.examples) {
doclet.examples = doclet.examples.map(function(example) {
var caption, code;
if (example.match(/^\s*<caption>([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) {
caption = RegExp.$1;
code = RegExp.$3;
}
return {
caption: caption || '',
code: code || example
@@ -326,7 +326,7 @@ exports.publish = function(taffyData, opts, tutorials) {
sourceFilePaths.push(resolvedSourcePath);
}
});
// update outdir if necessary, then create outdir
var packageInfo = ( find({kind: 'package'}) || [] ) [0];
if (packageInfo && packageInfo.name) {
@@ -350,8 +350,8 @@ exports.publish = function(taffyData, opts, tutorials) {
var staticFileScanner;
if (conf['default'].staticFiles) {
staticFilePaths = conf['default'].staticFiles.paths || [];
staticFileFilter = new (require('jsdoc/src/filter')).Filter(conf['default'].staticFiles);
staticFileScanner = new (require('jsdoc/src/scanner')).Scanner();
staticFileFilter = new (require('jsdoc-fork/lib/jsdoc/src/filter')).Filter(conf['default'].staticFiles);
staticFileScanner = new (require('jsdoc-fork/lib/jsdoc/src/scanner')).Scanner();
staticFilePaths.forEach(function(filePath) {
var extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter);
@@ -365,7 +365,7 @@ exports.publish = function(taffyData, opts, tutorials) {
});
});
}
if (sourceFilePaths.length) {
sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) );
}
@@ -383,7 +383,7 @@ exports.publish = function(taffyData, opts, tutorials) {
}
}
});
data().each(function(doclet) {
var url = helper.longnameToUrl[doclet.longname];
@@ -393,13 +393,13 @@ exports.publish = function(taffyData, opts, tutorials) {
else {
doclet.id = doclet.name;
}
if ( needsSignature(doclet) ) {
addSignatureParams(doclet);
addSignatureReturns(doclet);
}
});
// do this after the urls have all been generated
data().each(function(doclet) {
doclet.ancestors = getAncestorLinks(doclet);
@@ -407,13 +407,13 @@ exports.publish = function(taffyData, opts, tutorials) {
if (doclet.kind === 'member') {
addSignatureTypes(doclet);
}
if (doclet.kind === 'constant') {
addSignatureTypes(doclet);
doclet.kind = 'member';
}
});
var members = helper.getMembers(data);
members.tutorials = tutorials.children;
@@ -437,7 +437,7 @@ exports.publish = function(taffyData, opts, tutorials) {
}
if (members.globals.length) { generate('Global', [{kind: 'globalobj'}], globalUrl); }
// index page displays information from package.json and lists files
var files = find({kind: 'file'}),
packages = find({kind: 'package'});
@@ -454,14 +454,14 @@ exports.publish = function(taffyData, opts, tutorials) {
var namespaces = taffy(members.namespaces);
var mixins = taffy(members.mixins);
var externals = taffy(members.externals);
for (var longname in helper.longnameToUrl) {
if ( hasOwnProp.call(helper.longnameToUrl, longname) ) {
var myClasses = helper.find(classes, {longname: longname});
if (myClasses.length) {
generate('Class: ' + myClasses[0].name, myClasses, helper.longnameToUrl[longname]);
}
var myModules = helper.find(modules, {longname: longname});
if (myModules.length) {
generate('Module: ' + myModules[0].name, myModules, helper.longnameToUrl[longname]);
@@ -471,7 +471,7 @@ exports.publish = function(taffyData, opts, tutorials) {
if (myNamespaces.length) {
generate('Namespace: ' + myNamespaces[0].name, myNamespaces, helper.longnameToUrl[longname]);
}
var myMixins = helper.find(mixins, {longname: longname});
if (myMixins.length) {
generate('Mixin: ' + myMixins[0].name, myMixins, helper.longnameToUrl[longname]);
@@ -492,16 +492,16 @@ exports.publish = function(taffyData, opts, tutorials) {
content: tutorial.parse(),
children: tutorial.children
};
var tutorialPath = path.join(outdir, filename),
html = view.render('tutorial.tmpl', tutorialData);
// yes, you can use {@link} in tutorials too!
html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
fs.writeFileSync(tutorialPath, html, 'utf8');
}
// tutorials can have only one parent so there is no risk for loops
function saveChildren(node) {
node.children.forEach(function(child) {
config/jsdoc/info/publish.js
+15 -8
View File
@@ -6,11 +6,14 @@ var assert = require('assert');
var fs = require('fs');
var path = require('path');
var Promise = require('bluebird');
/**
* Publish hook for the JSDoc template. Writes to JSON stdout.
* @param {function} data The root of the Taffy DB containing doclet records.
* @param {Object} opts Options.
* @return {Promise} A promise that resolves when writing is complete.
*/
exports.publish = function(data, opts) {
@@ -168,13 +171,17 @@ exports.publish = function(data, opts) {
return (symbol.name in augments || symbol.virtual);
});
process.stdout.write(
JSON.stringify({
symbols: symbols,
defines: defines,
typedefs: typedefs,
externs: externs,
base: base
}, null, 2));
return new Promise(function(resolve, reject) {
process.stdout.write(
JSON.stringify({
symbols: symbols,
defines: defines,
typedefs: typedefs,
externs: externs,
base: base
}, null, 2), resolve);
});
};