docdash-extended-xkloveme/publish.js

JSDoc 模板 - 小康特制

/*global env: true */
'use strict';

var doop = require('jsdoc/util/doop');
var fs = require('jsdoc/fs');
var helper = require('jsdoc/util/templateHelper');
var logger = require('jsdoc/util/logger');
var path = require('jsdoc/path');
var taffy = require('@jsdoc/salty').taffy;
var template = require('jsdoc/template');
var util = require('util');
var categories = require('docdash-extended-xkloveme/categories.js');

var htmlsafe = helper.htmlsafe;
var linkto = helper.linkto;
var resolveAuthorLinks = helper.resolveAuthorLinks;
var hasOwnProp = Object.prototype.hasOwnProperty;

var data;
var view;

var outdir = path.normalize(env.opts.destination);

function copyFile(source, target, cb) {
    var cbCalled = false;

    var rd = fs.createReadStream(source);
    rd.on('error', function (err) {
        done(err);
    });
    var wr = fs.createWriteStream(target);
    wr.on('error', function (err) {
        done(err);
    });
    wr.on('close', function (ex) {
        done();
    });
    rd.pipe(wr);

    function done(err) {
        if (!cbCalled) {
            cb(err);
            cbCalled = true;
        }
    }
}

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 hashToLink(doclet, hash) {
    if (!/^(#.+)/.test(hash)) {
        return hash;
    }

    var url = helper.createLink(doclet);

    url = url.replace(/(#.+|$)/, hash);
    return '<a href="' + url + '">' + hash + '</a>';
}

function needsSignature(doclet) {
    var needsSig = false;

    // function and class definitions always get a signature
    if (doclet.kind === 'function' || (doclet.kind === 'class' && !doclet.hideconstructor)) {
        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 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 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 buildAttribsString(attribs) {
    var attribsString = '';

    if (attribs && attribs.length) {
        attribsString = htmlsafe(util.format('(%s) ', attribs.join(', ')));
    }

    return attribsString;
}

function addNonParamAttributes(items) {
    var types = [];

    items.forEach(function (item) {
        types = types.concat(buildItemTypeStrings(item));
    });

    return types;
}

function addSignatureParams(f) {
    var params = f.params ? addParamAttributes(f.params) : [];
    f.signature = util.format('%s(%s)', f.signature || '', params.join(', '));
}

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 addSignatureTypes(f) {
    var types = f.type ? buildItemTypeStrings(f) : [];

    f.signature = (f.signature || '') + '<span class="type-signature">' + (types.length ? ' :' + types.join('|') : '') + '</span>';
}

function addAttribs(f) {
    var attribs = helper.getAttribs(f);
    var attribsString = buildAttribsString(attribs);
    if (attribsString && attribsString.length) {
        f.attribs = util.format('<span class="type-signature type-signature-' + attribsString.replace(/\(/g, '').replace(/\)/g, '').trim() + '">%s</span>', attribsString);
    } else {
        f.attribs = util.format('<span class="type-signature">%s</span>', attribsString);
    }
}

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 generate(type, title, docs, filename, resolveLinks) {
    resolveLinks = resolveLinks === false ? false : true;

    var docData = {
        type: type,
        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');
}

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.<module:jsdoc/doclet.Doclet>} doclets - The array of classes and functions to
 * check.
 * @param {Array.<module:jsdoc/doclet.Doclet>} 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] = symbols[symbol.longname] || [];
        symbols[symbol.longname].push(symbol);
    });

    return modules.map(function (module) {
        if (symbols[module.longname]) {
            module.modules = symbols[module.longname]
                // Only show symbols that have a description. Make an exception for classes, because
                // we want to show the constructor-signature heading no matter what.
                .filter(function (symbol) {
                    return symbol.description || symbol.kind === 'class';
                })
                .map(function (symbol) {
                    symbol = doop(symbol);

                    if (symbol.kind === 'class' || (symbol.kind === 'function' && !symbol.hideconstructor)) {
                        symbol.name = symbol.name.replace('module:', '(require("') + '"))';
                    }

                    return symbol;
                });
        }
    });
}

function buildCategoriesNav(items, itemsSeen, linktoFn) {
    var nav = '';
    for (var [category, members] of Object.entries(items)) {
        var name = env.conf.categories[category].displayName;
        nav += buildMemberNav(members, name, itemsSeen, linktoFn);
    }
    return nav;
}

function buildMemberNav(items, itemHeading, itemsSeen, linktoFn) {
    var nav = '';

    if (items && items.length) {
        var itemsNav = '';
        var docdash = (env && env.conf && env.conf.docdash) || {};
        var level = typeof docdash.navLevel === 'number' && docdash.navLevel >= 0 ? docdash.navLevel : Infinity;

        items.forEach(function (item) {
            var displayName;
            var methods = find({ kind: 'function', memberof: item.longname });
            var members = find({ kind: 'member', memberof: item.longname });
            var conf = (env && env.conf) || {};
            var classes = '';

            // show private class?
            if (docdash.private === false && item.access === 'private') return;

            // depth to show?
            if (item.ancestors && item.ancestors.length > level) {
                classes += 'level-hide';
            }

            classes = classes ? ' class="' + classes + '"' : '';
            itemsNav += '<li' + classes + '>';
            if (!hasOwnProp.call(item, 'longname')) {
                itemsNav += linktoFn('', item.name);
            } else if (!hasOwnProp.call(itemsSeen, item.longname)) {
                if (conf.templates.default.useLongnameInNav) {
                    displayName = item.longname;
                } else {
                    displayName = item.name;
                }
                itemsNav += linktoFn(item.longname, displayName.replace(/\b(module|event):/g, ''));

                if (
                    docdash.static &&
                    members.find(function (m) {
                        return m.scope === 'static';
                    })
                ) {
                    itemsNav += "<ul class='members'>";

                    members.forEach(function (member) {
                        if (!member.scope === 'static') return;
                        itemsNav += "<li data-type='member'";
                        if (docdash.collapse) itemsNav += " style='display: none;'";
                        itemsNav += '>';
                        itemsNav += linkto(member.longname, member.name);
                        itemsNav += '</li>';
                    });

                    itemsNav += '</ul>';
                }

                if (methods.length) {
                    itemsNav += "<ul class='methods'>";

                    methods.forEach(function (method) {
                        if (docdash.static === false && method.scope === 'static') return;
                        if (docdash.private === false && method.access === 'private') return;

                        var navItem = '';
                        var navItemLink = linkto(method.longname, method.name);

                        navItem += "<li data-type='method'";
                        if (docdash.collapse) navItem += " style='display: none;'";
                        navItem += '>';
                        navItem += navItemLink;
                        navItem += '</li>';

                        itemsNav += navItem;
                    });

                    itemsNav += '</ul>';
                }

                itemsSeen[item.longname] = true;
            }
            itemsNav += '</li>';
        });

        if (itemsNav !== '<li></li>') {
            if (docdash.collapse === 'top') {
                nav += '<h3 class="collapsed_header">' + itemHeading + '</h3><ul class="collapse_top">' + itemsNav + '</ul>';
            } else {
                nav += '<h3>' + itemHeading + '</h3><ul>' + itemsNav + '</ul>';
            }
        }
    }

    return nav;
}

function linktoTutorial(longName, name) {
    return tutoriallink(name);
}

function linktoExternal(longName, name) {
    return linkto(longName, name.replace(/(^"|"$)/g, ''));
}

/**
 * Create the navigation sidebar.
 * @param {object} members The members that will be used to create the sidebar.
 * @param {array<object>} members.classes
 * @param {array<object>} members.externals
 * @param {array<object>} members.globals
 * @param {array<object>} members.mixins
 * @param {array<object>} members.modules
 * @param {array<object>} members.namespaces
 * @param {array<object>} members.tutorials
 * @param {array<object>} members.events
 * @param {array<object>} members.interfaces
 * @return {string} The HTML for the navigation sidebar.
 */

function buildNav(members, categoriesMembers) {
    var nav = '<h2><a href="index.html">主页</a></h2>';
    var seen = {};
    var seenTutorials = {};
    var docdash = (env && env.conf && env.conf.docdash) || {};
    if (docdash.menu) {
        for (var menu in docdash.menu) {
            nav += '<h2><a ';
            //add attributes
            for (var attr in docdash.menu[menu]) {
                nav += attr + '="' + docdash.menu[menu][attr] + '" ';
            }
            nav += '>' + menu + '</a></h2>';
        }
    }

    function buildMemberNavGlobal() {
        var ret = '';
        if (members.globals.length) {
            var globalNav = '';

            members.globals.forEach(function (g) {
                if ((docdash.typedefs || g.kind !== 'typedef') && !hasOwnProp.call(seen, g.longname)) {
                    globalNav += '<li>' + linkto(g.longname, g.name) + '</li>';
                }
                seen[g.longname] = true;
            });

            if (!globalNav) {
                // turn the heading into a link so you can actually get to the global page
                ret += '<h3>' + linkto('global', 'Global') + '</h3>';
            } else {
                if (docdash.collapse === 'top') {
                    ret += '<h3 class="collapsed_header">Global</h3><ul class="collapse_top">' + globalNav + '</ul>';
                } else {
                    ret += '<h3>Global</h3><ul>' + globalNav + '</ul>';
                }
            }
        }
        return ret;
    }
    var defaultOrder = ['Categories', 'Classes', 'Modules', 'Externals', 'Events', 'Namespaces', 'Mixins', 'Tutorials', 'Interfaces', 'Global'];
    var order = docdash.sectionOrder || defaultOrder;
    var sections = {
        Categories: () => buildCategoriesNav(categoriesMembers, seen, linkto),
        Classes: () => buildMemberNav(members.classes, 'Classes', seen, linkto),
        Modules: () => buildMemberNav(members.modules, 'Modules', {}, linkto),
        Externals: () => buildMemberNav(members.externals, 'Externals', seen, linktoExternal),
        Events: () => buildMemberNav(members.events, 'Events', seen, linkto),
        Namespaces: () => buildMemberNav(members.namespaces, 'Namespaces', seen, linkto),
        Mixins: () => buildMemberNav(members.mixins, 'Mixins', seen, linkto),
        Tutorials: () => buildMemberNav(members.tutorials, 'Tutorials', seenTutorials, linktoTutorial),
        Interfaces: () => buildMemberNav(members.interfaces, 'Interfaces', seen, linkto),
        Global: () => buildMemberNavGlobal()
    };
    order.forEach((section) => (nav += sections[section]()));

    return nav;
}

/**
    @param {TAFFY} taffyData See <http://taffydb.com/>.
    @param {object} opts
    @param {Tutorial} tutorials
 */
exports.publish = function (taffyData, opts, tutorials) {
    var docdash = (env && env.conf && env.conf.docdash) || {};
    data = taffyData;

    var conf = env.conf.templates || {};
    conf.default = conf.default || {};

    var templatePath = path.normalize(opts.template);
    view = new template.Template(path.join(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);

    docdash.sort !== false && data.sort('longname, version, since');
    helper.addEventListeners(data);

    var sourceFiles = {};
    var sourceFilePaths = [];
    data().each(function (doclet) {
        if (docdash.removeQuotes) {
            if (docdash.removeQuotes === 'all') {
                if (doclet.name) {
                    doclet.name = doclet.name.replace(/"/g, '');
                    doclet.name = doclet.name.replace(/'/g, '');
                }
                if (doclet.longname) {
                    doclet.longname = doclet.longname.replace(/"/g, '');
                    doclet.longname = doclet.longname.replace(/'/g, '');
                }
            } else if (docdash.removeQuotes === 'trim') {
                if (doclet.name) {
                    doclet.name = doclet.name.replace(/^"(.*)"$/, '$1');
                    doclet.name = doclet.name.replace(/^'(.*)'$/, '$1');
                }
                if (doclet.longname) {
                    doclet.longname = doclet.longname.replace(/^"(.*)"$/, '$1');
                    doclet.longname = doclet.longname.replace(/^'(.*)'$/, '$1');
                }
            }
        }
        doclet.attribs = '';

        if (doclet.examples) {
            doclet.examples = doclet.examples.map(function (example) {
                var caption, code;

                if (example && 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 || ''
                };
            });
        }
        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) {
        var subdirs = [outdir];

        if (packageInfo.name) {
            var packageName = packageInfo.name.split('/');

            if (packageName.length > 1 && docdash.scopeInOutputPath !== false) {
                subdirs.push(packageName[0]);
            }

            if (docdash.nameInOutputPath !== false) {
                subdirs.push(packageName.length > 1 ? packageName[1] : packageName[0]);
            }
        }

        if (packageInfo.version && docdash.versionInOutputPath !== false) {
            subdirs.push(packageInfo.version);
        }

        if (subdirs.length > 1) {
            outdir = path.join.apply(null, subdirs);
        }
    }

    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);
        copyFile(fileName, path.join(toDir, path.basename(fileName)), function (err) {
            if (err) console.err(err);
        });
    });

    // copy user-specified static files to outdir
    var staticFilePaths;
    var staticFileFilter;
    var staticFileScanner;
    if (conf.default.staticFiles) {
        // The canonical property name is `include`. We accept `paths` for backwards compatibility
        // with a bug in JSDoc 3.2.x.
        staticFilePaths = conf.default.staticFiles.include || 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);
                copyFile(fileName, path.join(toDir, path.basename(fileName)), function (err) {
                    if (err) console.err(err);
                });
            });
        });
    }

    if (sourceFilePaths.length) {
        sourceFiles = shortenPaths(sourceFiles, path.commonPrefix(sourceFilePaths));
    }
    data().each(function (doclet) {
        var url = helper.createLink(doclet);
        if (docdash.noURLEncode) {
            url = decodeURI(url);
        }
        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);
    var categoriesMembers = {};
    if (env.conf.categoryList) {
        for (var category of env.conf.categoryList) {
            categoriesMembers[category] = categories.getMembers(data, category);
        }
    }
    members.tutorials = tutorials.children;

    // 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;

    // once for all
    view.nav = buildNav(members, categoriesMembers);
    attachModuleSymbols(find({ 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' });
    var packages = find({ kind: 'package' });

    generate('', 'Home', packages.concat([{ kind: 'mainpage', readme: opts.readme, longname: opts.mainpagetitle ? opts.mainpagetitle : 'Main Page' }]).concat(files), indexUrl);

    // common nav generation, no need for templating here, we already have full html
    if (docdash.commonNav) {
        fs.writeFileSync(path.join(outdir, 'nav.inc.html'), view.nav, 'utf8');
    }

    // 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);
    var interfaces = taffy(members.interfaces);

    Object.keys(helper.longnameToUrl).forEach(function (longname) {
        var myModules = helper.find(modules, { longname: longname });
        if (myModules.length) {
            generate('Module', myModules[0].name, myModules, helper.longnameToUrl[longname]);
        }

        var myClasses = helper.find(classes, { longname: longname });
        if (myClasses.length) {
            generate('Class', myClasses[0].name, myClasses, 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]);
        }

        var myInterfaces = helper.find(interfaces, { longname: longname });
        if (myInterfaces.length) {
            generate('Interface', myInterfaces[0].name, myInterfaces, 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);
        var 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) {
            generateTutorial('Tutorial: ' + child.title, child, helper.tutorialToUrl(child.name));
            saveChildren(child);
        });
    }

    saveChildren(tutorials);
};