/** * Created by Aleksey Chichenkov 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*([\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 foo } 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 || '') + '' + (types.length ? ' :' + types.join('|') : '') + ''; } 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%s', 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 = '' + (f.signature || '') + '' + '' + returnTypesString + ''; } function addAttribs(f) { var attribs = helper.getAttribs(f); var attribsString = buildAttribsString(attribs); f.attribs = util.format('%s', attribsString); } module.exports = Render;