initi.doc/templates/initi2/render.js

550 lines
17 KiB
JavaScript
Raw Normal View History

2020-03-31 11:06:26 +00:00
/**
* 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 = '&hellip;' + 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( ' &rarr; %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;