/*global env: true */ 'use strict'; var template = require('jsdoc/template'), fs = require('jsdoc/fs'), path = require('jsdoc/path'), taffy = require('taffydb').taffy, logger = require('jsdoc/util/logger'), helper = require('jsdoc/util/templateHelper'), htmlsafe = helper.htmlsafe, linkto = helper.linkto, resolveAuthorLinks = helper.resolveAuthorLinks, scopeToPunc = helper.scopeToPunc, hasOwnProp = Object.prototype.hasOwnProperty, data, view, outdir = env.opts.destination; function find(spec) { return helper.find(data, spec); } function tutoriallink(tutorial) { return helper.toTutorial(tutorial, null, { tag: 'em', classname: 'disabled', prefix: 'Tutorial: ' }); } function getAncestorLinks(doclet) { return helper.getAncestorLinks(data, doclet); } function getCategoryLink(className, cat) { return '' + cat + ' methods'; } function hashToLink(doclet, hash) { if ( !/^(#.+)/.test(hash) ) { return hash; } var url = helper.createLink(doclet); url = url.replace(/(#.+|$)/, hash); return '' + hash + ''; } 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; } } } return needsSig; } 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 = '' + (f.signature || '') + '' + '' + (returnTypes && returnTypes.length ? ' → {' + returnTypes.join('|') + '}' : '') + ''; } function addSignatureTypes(f) { var types = helper.getSignatureTypes(f); f.signature = (f.signature || '') + ''+(types.length? ' :'+types.join('|') : '')+''; } function addAttribs(f) { var attribs = helper.getAttribs(f); f.attribs = '' + htmlsafe(attribs.length ? // we want the template output to say 'abstract', not 'virtual' '<' + attribs.join(', ').replace('virtual', 'abstract') + '> ' : '') + ''; } 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; } return doclet.meta.path && doclet.meta.path !== 'null' ? path.join(doclet.meta.path, doclet.meta.filename) : doclet.meta.filename; } function generate(title, docs, filename, resolveLinks) { resolveLinks = resolveLinks === false ? false : true; var docData = { 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 foo } // Ensure
 tags have pretty print class
    html = html.replace(/
/g, '
');

    fs.writeFileSync(outpath, html, 'utf8');
}

function generateSourceFiles(sourceFiles, encoding) {
    encoding = encoding || 'utf8';
    Object.keys(sourceFiles).forEach(function(file) {
        var source;
        // links are keyed to the shortened path in each doclet's `meta.shortpath` property
        var sourceOutfile = helper.getUniqueFilename(sourceFiles[file].shortened);
        helper.registerLink(sourceFiles[file].shortened, sourceOutfile);

        try {
            source = {
                kind: 'source',
                code: helper.htmlsafe( fs.readFileSync(sourceFiles[file].resolved, encoding) )
            };
        }
        catch(e) {
            logger.error('Error while generating source file %s: %s', file, e.message);
        }

        generate('Source: ' + sourceFiles[file].shortened, [source], sourceOutfile,
            false);
    });
}

/**
 * Look for classes or functions with the same name as modules (which indicates that the module
 * 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.} doclets - The array of classes and functions to
 * check.
 * @param {Array.} modules - The array of module doclets to search.
 */
function attachModuleSymbols(doclets, modules) {
    var symbols = {};

    // build a lookup table
    doclets.forEach(function(symbol) {
        symbols[symbol.longname] = symbol;
    });

    return modules.map(function(module) {
        if (symbols[module.longname]) {
            module.module = symbols[module.longname];
            module.module.name = module.module.name.replace('module:', 'require("') + '")';
        }
    });
}

function buildReadmeNav(readme) {
    var nav = '';

    var prevLevel = '0';
    nav += '
    '; readme = readme.replace(/([^<]*)<\/h[23]>/g, function(match, level, title) { if (title.trim().length > 0) { var titlelink = title.toLowerCase().replace(/[^a-z]/g, '-'); if (level === '2') { if (prevLevel === '2' || prevLevel === '3') { nav += '
'; } nav += '
  • ' + title + '
    • '; } else { nav += '
    • ' + title + '
    • '; } prevLevel = level; match = '' + match; } return match; }); nav += '
    '; return { nav: nav, readme: readme }; } /** * Create the navigation sidebar. * @param {String} readmeNav The readme TOC * @param {object} members The members that will be used to create the sidebar. * @param {array} members.classes * @param {array} members.externals * @param {array} members.globals * @param {array} members.mixins * @param {array} members.modules * @param {array} members.namespaces * @param {array} members.tutorials * @param {array} members.events * @return {string} The HTML for the navigation sidebar. */ function buildNav(readmeNav, members) { var nav = '

    Index

    ' + readmeNav, seen = {}, hasClassList = false, classNav = '', globalNav = ''; if (members.modules.length) { nav += '

    Modules

      '; members.modules.forEach(function(m) { if ( !hasOwnProp.call(seen, m.longname) ) { nav += '
    • '+linkto(m.longname, m.name)+'
    • '; } seen[m.longname] = true; }); nav += '
    '; } if (members.externals.length) { nav += '

    Externals

      '; members.externals.forEach(function(e) { if ( !hasOwnProp.call(seen, e.longname) ) { nav += '
    • '+linkto( e.longname, e.name.replace(/(^"|"$)/g, '') )+'
    • '; } seen[e.longname] = true; }); nav += '
    '; } if (members.classes.length) { members.classes.forEach(function(c) { if ( !hasOwnProp.call(seen, c.longname) ) { classNav += '
  • '+linkto(c.longname, c.name)+'
  • '; if (c.longname in members.categories) { classNav += '
      ' + members.categories[c.longname].reduce(function(nav, cat) { return nav + '
    • ' + getCategoryLink(c.longname, cat) + '
    • '; }, '') + '
    '; } } seen[c.longname] = true; }); if (classNav !== '') { nav += '

    Classes

      '; nav += classNav; nav += '
    '; } } /*if (members.events.length) { nav += '

    Events

      '; members.events.forEach(function(e) { if ( !hasOwnProp.call(seen, e.longname) ) { nav += '
    • '+linkto(e.longname, e.name)+'
    • '; } seen[e.longname] = true; }); nav += '
    '; }*/ if (members.namespaces.length) { nav += '

    Namespaces

      '; members.namespaces.forEach(function(n) { if ( !hasOwnProp.call(seen, n.longname) ) { nav += '
    • '+linkto(n.longname, n.name)+'
    • '; } seen[n.longname] = true; }); nav += '
    '; } if (members.mixins.length) { nav += '

    Mixins

      '; members.mixins.forEach(function(m) { if ( !hasOwnProp.call(seen, m.longname) ) { nav += '
    • '+linkto(m.longname, m.name)+'
    • '; } seen[m.longname] = true; }); nav += '
    '; } if (members.tutorials.length) { nav += '

    Tutorials

      '; members.tutorials.forEach(function(t) { nav += '
    • '+tutoriallink(t.name)+'
    • '; }); nav += '
    '; } if (members.globals.length) { members.globals.forEach(function(g) { if ( g.kind !== 'typedef' && !hasOwnProp.call(seen, g.longname) ) { globalNav += '
  • ' + linkto(g.longname, g.name) + '
  • '; } seen[g.longname] = true; }); if (!globalNav) { // turn the heading into a link so you can actually get to the global page nav += '

    ' + linkto('global', 'Global') + '

    '; } else { nav += '

    Global

      ' + globalNav + '
    '; } } return nav; } /** @param {TAFFY} taffyData See . @param {object} opts @param {Tutorial} tutorials */ exports.publish = function(taffyData, opts, tutorials) { data = taffyData; var conf = env.conf.templates || {}; conf['default'] = conf['default'] || {}; 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'); // don't call registerLink() on this one! 'index' is also a valid longname var globalUrl = helper.getUniqueFilename('global'); helper.registerLink('global', globalUrl); // set up templating view.layout = conf['default'].layoutFile ? path.getResourcePath(path.dirname(conf['default'].layoutFile), path.basename(conf['default'].layoutFile) ) : 'layout.tmpl'; // set up tutorials for helper helper.setTutorials(tutorials); data = helper.prune(data); data.sort('longname, version, since'); helper.addEventListeners(data); var sourceFiles = {}; 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*([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) { caption = RegExp.$1; code = RegExp.$3; } return { caption: caption || '', code: code || example }; }); } if (doclet.see) { doclet.see.forEach(function(seeItem, i) { doclet.see[i] = hashToLink(doclet, seeItem); }); } // build a list of source files var sourcePath; if (doclet.meta) { sourcePath = getPathFromDoclet(doclet); sourceFiles[sourcePath] = { resolved: sourcePath, shortened: null }; if (sourceFilePaths.indexOf(sourcePath) === -1) { sourceFilePaths.push(sourcePath); } } }); // update outdir if necessary, then create outdir var packageInfo = ( find({kind: 'package'}) || [] ) [0]; if (packageInfo && packageInfo.name) { outdir = path.join(outdir, packageInfo.name, packageInfo.version); } fs.mkPath(outdir); // copy the template's static files to outdir var fromDir = path.join(templatePath, 'static'); var staticFiles = fs.ls(fromDir, 3); staticFiles.forEach(function(fileName) { var toDir = fs.toDir( fileName.replace(fromDir, outdir) ); fs.mkPath(toDir); fs.copyFileSync(fileName, toDir); }); // copy user-specified static files to outdir var staticFilePaths; var staticFileFilter; 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(); staticFilePaths.forEach(function(filePath) { var extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter); extraStaticFiles.forEach(function(fileName) { var sourcePath = fs.toDir(filePath); var toDir = fs.toDir( fileName.replace(sourcePath, outdir) ); fs.mkPath(toDir); fs.copyFileSync(fileName, toDir); }); }); } if (sourceFilePaths.length) { sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) ); } data().each(function(doclet) { var url = helper.createLink(doclet); helper.registerLink(doclet.longname, url); // add a shortened version of the full path var docletPath; if (doclet.meta) { docletPath = getPathFromDoclet(doclet); docletPath = sourceFiles[docletPath].shortened; if (docletPath) { doclet.meta.shortpath = docletPath; } } }); 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); } }); // do this after the urls have all been generated data().each(function(doclet) { doclet.ancestors = getAncestorLinks(doclet); if (doclet.kind === 'member') { addSignatureTypes(doclet); addAttribs(doclet); } if (doclet.kind === 'constant') { addSignatureTypes(doclet); addAttribs(doclet); doclet.kind = 'member'; } }); var members = helper.getMembers(data); members.tutorials = tutorials.children; members.categories = data('method').get().reduce(function(cats, method) { if (!(method.memberof in cats)) { cats[method.memberof] = []; } var cat = method.category || 'Other'; if (cats[method.memberof].indexOf(cat) === -1) { cats[method.memberof].push(cat); cats[method.memberof] = cats[method.memberof].sort(); } return cats; }, {}); // output pretty-printed source files by default var outputSourceFiles = conf['default'] && conf['default'].outputSourceFiles !== false ? true : false; // add template helpers view.find = find; view.linkto = linkto; view.resolveAuthorLinks = resolveAuthorLinks; view.tutoriallink = tutoriallink; view.htmlsafe = htmlsafe; view.outputSourceFiles = outputSourceFiles; // Build readme nav var readmeNav = buildReadmeNav(opts.readme); opts.readme = readmeNav.readme; // once for all view.nav = buildNav(readmeNav.nav, members); attachModuleSymbols( find({ kind: ['class', 'function'], longname: {left: 'module:'} }), members.modules ); // generate the pretty-printed source files first so other pages can link to them if (outputSourceFiles) { generateSourceFiles(sourceFiles, opts.encoding); } 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'}); generate('Index', packages.concat( [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}] ).concat(files), indexUrl); // set up the lists that we'll use to generate pages var classes = taffy(members.classes); var modules = taffy(members.modules); var namespaces = taffy(members.namespaces); var mixins = taffy(members.mixins); var externals = taffy(members.externals); Object.keys(helper.longnameToUrl).forEach(function(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]); } var myNamespaces = helper.find(namespaces, {longname: longname}); 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]); } var myExternals = helper.find(externals, {longname: longname}); if (myExternals.length) { generate('External: ' + myExternals[0].name, myExternals, helper.longnameToUrl[longname]); } }); // TODO: move the tutorial functions to templateHelper.js function generateTutorial(title, tutorial, filename) { var tutorialData = { title: title, header: tutorial.title, 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 foo 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) { generateTutorial('Tutorial: ' + child.title, child, helper.tutorialToUrl(child.name)); saveChildren(child); }); } saveChildren(tutorials); };