550 lines
17 KiB
JavaScript
550 lines
17 KiB
JavaScript
/**
|
|
* Created by Aleksey Chichenkov <a.chichenkov@initi.ru> on 12/16/19.
|
|
*/
|
|
const fs = require("fs");
|
|
const util = require('util');
|
|
const helper = require('jsdoc/util/templateHelper');
|
|
const path = require('jsdoc/path');
|
|
const jfs = require('jsdoc/fs');
|
|
const env = require('jsdoc/env');
|
|
const template = require('jsdoc/template');
|
|
const taffy = require('taffydb').taffy;
|
|
const htmlsafe = helper.htmlsafe;
|
|
const linkto = helper.linkto;
|
|
|
|
class Render {
|
|
|
|
/**
|
|
*
|
|
* @param _taffyData
|
|
* @param _opts
|
|
*/
|
|
constructor (_taffyData, _opts, _tutorials) {
|
|
this._taffyData = _taffyData;
|
|
this._opts = _opts;
|
|
this._tutorials = _tutorials;
|
|
|
|
this._sourceFiles = {};
|
|
this._sourceFilePaths = [];
|
|
}
|
|
|
|
init() {
|
|
this._outdir = path.normalize(this._opts.destination);
|
|
this._templatePath = path.normalize(this._opts.template);
|
|
this._conf = env.conf.templates || {};
|
|
this._conf.default = this._conf.default || {};
|
|
this._indexUrl = helper.getUniqueFilename('index');
|
|
this._outputSourceFiles = this._conf.default && this._conf.default.outputSourceFiles !== false;
|
|
|
|
this._upgradeData();
|
|
this._createFileWithDocklets();
|
|
this._createOutdir();
|
|
this._copyStaticFiles();
|
|
this._processExamples();
|
|
this._processSee();
|
|
this._buildListSourceFiles();
|
|
this._buildLinks();
|
|
this._addAttribsAndSignature(); // what it do is
|
|
this._buildMenu();
|
|
this._findMembers();
|
|
this._initTemplate();
|
|
this._generateFiles();
|
|
|
|
// index page displays information from package.json and lists files
|
|
var files = this.find({kind: 'file'});
|
|
var packages = this.find({kind: 'package'});
|
|
this.generate('Documentation: GUI 2.9.1-develop',
|
|
packages.concat(
|
|
[{
|
|
kind: 'mainpage',
|
|
readme: this._opts.readme,
|
|
longname: (this._opts.mainpagetitle) ? this._opts.mainpagetitle : 'Main Page'
|
|
}]
|
|
).concat(files), this._indexUrl);
|
|
}
|
|
|
|
_upgradeData () {
|
|
this._data = helper.prune(this._taffyData);
|
|
this._data.sort('longname, version, since');
|
|
}
|
|
|
|
_createFileWithDocklets () {
|
|
var data = [];
|
|
|
|
this._taffyData().each(function (_data) {
|
|
data.push(_data);
|
|
});
|
|
|
|
fs.writeFileSync("taffy.json", JSON.stringify(data, true, 3));
|
|
}
|
|
|
|
_createOutdir () {
|
|
var packageInfo = (this.find({kind: 'package'}) || [])[0];
|
|
|
|
if (packageInfo && packageInfo.name) {
|
|
this._outdir = path.join(this._outdir, packageInfo.name, (packageInfo.version || ''));
|
|
}
|
|
jfs.mkPath(this._outdir);
|
|
}
|
|
|
|
_copyStaticFiles () {
|
|
var fromDir = path.join(this._templatePath, 'static');
|
|
var staticFiles = jfs.ls(fromDir, 3);
|
|
|
|
staticFiles.forEach(function(fileName) {
|
|
var toDir = jfs.toDir( fileName.replace(fromDir, outdir) );
|
|
|
|
jfs.mkPath(toDir);
|
|
jfs.copyFileSync(fileName, toDir);
|
|
});
|
|
|
|
if (this._conf.default.staticFiles) {
|
|
// The canonical property name is `include`. We accept `paths` for backwards compatibility
|
|
// with a bug in JSDoc 3.2.x.
|
|
var staticFilePaths = this._conf.default.staticFiles.include ||
|
|
this._conf.default.staticFiles.paths ||
|
|
[];
|
|
var staticFileFilter = new (require('jsdoc/src/filter')).Filter(this._conf.default.staticFiles);
|
|
var staticFileScanner = new (require('jsdoc/src/scanner')).Scanner();
|
|
|
|
staticFilePaths.forEach(function(filePath) {
|
|
var extraStaticFiles;
|
|
|
|
filePath = path.resolve(env.pwd, filePath);
|
|
extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter);
|
|
|
|
extraStaticFiles.forEach(function(fileName) {
|
|
var sourcePath = jfs.toDir(filePath);
|
|
var toDir = jfs.toDir( fileName.replace(sourcePath, outdir) );
|
|
|
|
jfs.mkPath(toDir);
|
|
jfs.copyFileSync(fileName, toDir);
|
|
}.bind(this));
|
|
}.bind(this));
|
|
}
|
|
|
|
}
|
|
|
|
_processExamples (){
|
|
this._data().each(function(doclet) {
|
|
doclet.attribs = '';
|
|
|
|
if (doclet.examples) {
|
|
doclet.examples = doclet.examples.map(function (example) {
|
|
var caption;
|
|
var 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
|
|
};
|
|
}.bind(this));
|
|
}
|
|
}.bind(this))
|
|
}
|
|
|
|
_processSee (){
|
|
this._data().each(function(doclet) {
|
|
if (doclet.see) {
|
|
doclet.see.forEach(function(seeItem, i) {
|
|
doclet.see[i] = hashToLink(doclet, seeItem);
|
|
});
|
|
}
|
|
}.bind(this))
|
|
}
|
|
|
|
_buildListSourceFiles (){
|
|
var sourcePath;
|
|
|
|
this._data().each(function(doclet) {
|
|
// build a list of source files
|
|
if (doclet.meta) {
|
|
sourcePath = getPathFromDoclet(doclet);
|
|
this._sourceFiles[sourcePath] = {
|
|
resolved: sourcePath,
|
|
shortened: null
|
|
};
|
|
if (this._sourceFilePaths.indexOf(sourcePath) === -1) {
|
|
this._sourceFilePaths.push(sourcePath);
|
|
}
|
|
}
|
|
}.bind(this));
|
|
|
|
if (this._sourceFilePaths.length) {
|
|
this._sourceFiles = shortenPaths( this._sourceFiles, path.commonPrefix(this._sourceFilePaths) );
|
|
}
|
|
}
|
|
|
|
_buildLinks () {
|
|
this._data().each(function(doclet) {
|
|
var docletPath;
|
|
var url = helper.createLink(doclet);
|
|
|
|
helper.registerLink(doclet.longname, url);
|
|
|
|
// add a shortened version of the full path
|
|
if (doclet.meta) {
|
|
docletPath = getPathFromDoclet(doclet);
|
|
docletPath = this._sourceFiles[docletPath].shortened;
|
|
if (docletPath) {
|
|
doclet.meta.shortpath = docletPath;
|
|
}
|
|
}
|
|
}.bind(this));
|
|
}
|
|
|
|
_addAttribsAndSignature () {
|
|
this._data().each(function (doclet) {
|
|
var url = helper.longnameToUrl[doclet.longname];
|
|
|
|
if (url.indexOf('#') > -1) {
|
|
doclet.id = helper.longnameToUrl[doclet.longname].split(/#/).pop();
|
|
} else {
|
|
doclet.id = doclet.name;
|
|
}
|
|
|
|
if (needsSignature(doclet)) {
|
|
addSignatureParams(doclet);
|
|
addSignatureReturns(doclet);
|
|
addAttribs(doclet);
|
|
}
|
|
}.bind(this));
|
|
|
|
// do this after the urls have all been generated
|
|
this._data().each(function(doclet) {
|
|
doclet.ancestors = this.getAncestorLinks(doclet);
|
|
|
|
if (doclet.kind === 'member') {
|
|
addSignatureTypes(doclet);
|
|
addAttribs(doclet);
|
|
}
|
|
|
|
if (doclet.kind === 'constant') {
|
|
addSignatureTypes(doclet);
|
|
addAttribs(doclet);
|
|
doclet.kind = 'member';
|
|
}
|
|
}.bind(this));
|
|
|
|
}
|
|
|
|
_buildMenu () {
|
|
|
|
}
|
|
|
|
_findMembers() {
|
|
this._members = helper.getMembers(this._data);
|
|
this._members.tutorials = this._tutorials.children;
|
|
}
|
|
|
|
_initTemplate () {
|
|
this._view = new template.Template( path.join(this._templatePath, 'tmpl') );
|
|
this._view.find = this.find.bind(this);
|
|
this._view.linkto = linkto;
|
|
this._view.resolveAuthorLinks = helper.resolveAuthorLinks;
|
|
this._view.tutoriallink = tutoriallink;
|
|
this._view.htmlsafe = htmlsafe;
|
|
this._view.outputSourceFiles = this._outputSourceFiles;
|
|
|
|
// set up templating
|
|
if(this._conf.default.layoutFile) {
|
|
this._view.layout = path.getResourcePath(path.dirname(this._conf.default.layoutFile), path.basename(this._conf.default.layoutFile))
|
|
} else {
|
|
this._view.layout = 'layout.tmpl'
|
|
}
|
|
}
|
|
|
|
_generateFiles() {
|
|
// output pretty-printed source files by default
|
|
if (this._outputSourceFiles) {
|
|
this.generateSourceFiles(this._sourceFiles, this._opts.encoding);
|
|
}
|
|
|
|
// set up the lists that we'll use to generate pages
|
|
this._classes = taffy(this._members.classes);
|
|
this._modules = taffy(this._members.modules);
|
|
this._namespaces = taffy(this._members.namespaces);
|
|
this._mixins = taffy(this._members.mixins);
|
|
this._externals = taffy(this._members.externals);
|
|
this._interfaces = taffy(this._members.interfaces);
|
|
|
|
Object.keys(helper.longnameToUrl).forEach(function(longname) {
|
|
var myClasses = helper.find(this._classes, {longname: longname});
|
|
var myExternals = helper.find(this._externals, {longname: longname});
|
|
var myInterfaces = helper.find(this._interfaces, {longname: longname});
|
|
var myMixins = helper.find(this._mixins, {longname: longname});
|
|
var myModules = helper.find(this._modules, {longname: longname});
|
|
var myNamespaces = helper.find(this._namespaces, {longname: longname});
|
|
|
|
if (myModules.length) {
|
|
this.generate('Module: ' + myModules[0].name, myModules, helper.longnameToUrl[longname]);
|
|
}
|
|
|
|
if (myClasses.length) {
|
|
this.generate(myClasses[0].name, myClasses, helper.longnameToUrl[longname]);
|
|
}
|
|
|
|
if (myNamespaces.length) {
|
|
this.generate(myNamespaces[0].name, myNamespaces, helper.longnameToUrl[longname]);
|
|
}
|
|
|
|
if (myMixins.length) {
|
|
this.generate('Mixin: ' + myMixins[0].name, myMixins, helper.longnameToUrl[longname]);
|
|
}
|
|
|
|
if (myExternals.length) {
|
|
this.generate('External: ' + myExternals[0].name, myExternals, helper.longnameToUrl[longname]);
|
|
}
|
|
|
|
if (myInterfaces.length) {
|
|
this.generate('Interface: ' + myInterfaces[0].name, myInterfaces, helper.longnameToUrl[longname]);
|
|
}
|
|
}.bind(this));
|
|
}
|
|
|
|
generate(title, docs, filename, resolveLinks) {
|
|
var docData;
|
|
var html;
|
|
var outpath;
|
|
|
|
resolveLinks = resolveLinks !== false;
|
|
|
|
docData = {
|
|
env: env,
|
|
title: title,
|
|
docs: docs
|
|
};
|
|
|
|
outpath = path.join(this._outdir, filename);
|
|
|
|
html = this._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');
|
|
}
|
|
|
|
generateSourceFiles(sourceFiles, encoding) {
|
|
this._encoding = encoding || 'utf8';
|
|
Object.keys(this._sourceFiles).forEach(function(file) {
|
|
var source;
|
|
// links are keyed to the shortened path in each doclet's `meta.shortpath` property
|
|
var sourceOutfile = helper.getUniqueFilename(this._sourceFiles[file].shortened);
|
|
|
|
helper.registerLink(this._sourceFiles[file].shortened, sourceOutfile);
|
|
|
|
try {
|
|
source = {
|
|
kind: 'source',
|
|
code: helper.htmlsafe( fs.readFileSync(this._sourceFiles[file].resolved, this._encoding) )
|
|
};
|
|
}
|
|
catch (e) {
|
|
logger.error('Error while generating source file %s: %s', file, e.message);
|
|
}
|
|
|
|
this.generate('Source: ' + this._sourceFiles[file].shortened, [source], sourceOutfile, false);
|
|
}.bind(this));
|
|
}
|
|
|
|
getAncestorLinks(doclet) {
|
|
return helper.getAncestorLinks(this._data, doclet);
|
|
}
|
|
|
|
find(spec) {
|
|
return helper.find(this._data, spec);
|
|
}
|
|
}
|
|
|
|
|
|
// local functions
|
|
|
|
function tutoriallink(tutorial) {
|
|
return helper.toTutorial(tutorial, null, {
|
|
tag: 'em',
|
|
classname: 'disabled',
|
|
prefix: 'Tutorial: '
|
|
});
|
|
}
|
|
|
|
function shortenPaths(files, commonPrefix) {
|
|
Object.keys(files).forEach(function(file) {
|
|
files[file].shortened = files[file].resolved.replace(commonPrefix, '')
|
|
// always use forward slashes
|
|
.replace(/\\/g, '/');
|
|
});
|
|
|
|
return files;
|
|
}
|
|
|
|
function getPathFromDoclet(doclet) {
|
|
if (!doclet.meta) {
|
|
return null;
|
|
}
|
|
|
|
return doclet.meta.path && doclet.meta.path !== 'null' ?
|
|
path.join(doclet.meta.path, doclet.meta.filename) :
|
|
doclet.meta.filename;
|
|
}
|
|
|
|
function needsSignature(doclet) {
|
|
var needsSig = false;
|
|
|
|
// function and class definitions always get a signature
|
|
if (doclet.kind === 'function' || doclet.kind === 'class') {
|
|
needsSig = true;
|
|
}
|
|
// typedefs that contain functions get a signature, too
|
|
else if (doclet.kind === 'typedef' && doclet.type && doclet.type.names &&
|
|
doclet.type.names.length) {
|
|
for (var i = 0, l = doclet.type.names.length; i < l; i++) {
|
|
if (doclet.type.names[i].toLowerCase() === 'function') {
|
|
needsSig = true;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
// and namespaces that are functions get a signature (but finding them is a
|
|
// bit messy)
|
|
else if (doclet.kind === 'namespace' && doclet.meta && doclet.meta.code &&
|
|
doclet.meta.code.type && doclet.meta.code.type.match(/[Ff]unction/)) {
|
|
needsSig = true;
|
|
}
|
|
|
|
return needsSig;
|
|
}
|
|
|
|
function addSignatureTypes(f) {
|
|
var types = f.type ? buildItemTypeStrings(f) : [];
|
|
|
|
f.signature = (f.signature || '') + '<span class="type-signature">' +
|
|
(types.length ? ' :' + types.join('|') : '') + '</span>';
|
|
}
|
|
|
|
function getSignatureAttributes(item) {
|
|
var attributes = [];
|
|
|
|
if (item.optional) {
|
|
attributes.push('opt');
|
|
}
|
|
|
|
if (item.nullable === true) {
|
|
attributes.push('nullable');
|
|
}
|
|
else if (item.nullable === false) {
|
|
attributes.push('non-null');
|
|
}
|
|
|
|
return attributes;
|
|
}
|
|
|
|
|
|
function updateItemName(item) {
|
|
var attributes = getSignatureAttributes(item);
|
|
var itemName = item.name || '';
|
|
|
|
if (item.variable) {
|
|
itemName = '…' + itemName;
|
|
}
|
|
|
|
if (attributes && attributes.length) {
|
|
itemName = util.format( '%s<span class="signature-attributes">%s</span>', itemName,
|
|
attributes.join(', ') );
|
|
}
|
|
|
|
return itemName;
|
|
}
|
|
|
|
function addParamAttributes(params) {
|
|
return params.filter(function(param) {
|
|
return param.name && param.name.indexOf('.') === -1;
|
|
}).map(updateItemName);
|
|
}
|
|
|
|
function addSignatureParams(f) {
|
|
var params = f.params ? addParamAttributes(f.params) : [];
|
|
|
|
f.signature = util.format( '%s(%s)', (f.signature || ''), params.join(', ') );
|
|
}
|
|
|
|
function buildItemTypeStrings(item) {
|
|
var types = [];
|
|
|
|
if (item && item.type && item.type.names) {
|
|
item.type.names.forEach(function(name) {
|
|
types.push( linkto(name, htmlsafe(name)) );
|
|
});
|
|
}
|
|
|
|
return types;
|
|
}
|
|
|
|
|
|
function addNonParamAttributes(items) {
|
|
var types = [];
|
|
|
|
items.forEach(function(item) {
|
|
types = types.concat( buildItemTypeStrings(item) );
|
|
});
|
|
|
|
return types;
|
|
}
|
|
|
|
function buildAttribsString(attribs) {
|
|
var attribsString = '';
|
|
|
|
if (attribs && attribs.length) {
|
|
attribsString = htmlsafe( util.format('(%s) ', attribs.join(', ')) );
|
|
}
|
|
|
|
return attribsString;
|
|
}
|
|
|
|
function addSignatureReturns(f) {
|
|
var attribs = [];
|
|
var attribsString = '';
|
|
var returnTypes = [];
|
|
var returnTypesString = '';
|
|
var source = f.yields || f.returns;
|
|
|
|
// jam all the return-type attributes into an array. this could create odd results (for example,
|
|
// if there are both nullable and non-nullable return types), but let's assume that most people
|
|
// who use multiple @return tags aren't using Closure Compiler type annotations, and vice-versa.
|
|
if (source) {
|
|
source.forEach(function(item) {
|
|
helper.getAttribs(item).forEach(function(attrib) {
|
|
if (attribs.indexOf(attrib) === -1) {
|
|
attribs.push(attrib);
|
|
}
|
|
});
|
|
});
|
|
|
|
attribsString = buildAttribsString(attribs);
|
|
}
|
|
|
|
if (source) {
|
|
returnTypes = addNonParamAttributes(source);
|
|
}
|
|
if (returnTypes.length) {
|
|
returnTypesString = util.format( ' → %s{%s}', attribsString, returnTypes.join('|') );
|
|
}
|
|
|
|
f.signature = '<span class="signature">' + (f.signature || '') + '</span>' +
|
|
'<span class="type-signature">' + returnTypesString + '</span>';
|
|
}
|
|
|
|
function addAttribs(f) {
|
|
var attribs = helper.getAttribs(f);
|
|
var attribsString = buildAttribsString(attribs);
|
|
|
|
f.attribs = util.format('<span class="type-signature">%s</span>', attribsString);
|
|
}
|
|
|
|
module.exports = Render; |