publish.js

/*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("taffydb").taffy
var template = require("jsdoc/template")
var util = require("util")

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

var data
var view

var outdir = path.normalize(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 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") {
        needsSig = true
    } else if (
        doclet.kind === "typedef" &&
        doclet.type &&
        doclet.type.names &&
        doclet.type.names.length
    ) {
        // typedefs that contain functions get a signature, too
        for (var i = 0, l = doclet.type.names.length; i < l; i++) {
            if (doclet.type.names[i].toLowerCase() === "function") {
                needsSig = true
                break
            }
        }
    } else if (
        doclet.kind === 'namespace' &&
        doclet.meta &&
        doclet.meta.code &&
        doclet.meta.code.type &&
        doclet.meta.code.type.match(/[Ff]unction/)
    ) {
        // and namespaces that are functions get a signature (but finding them is a
        // bit messy)
        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)

    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.name = symbol.name.replace("module:", '(require("') + '"))'
                    }

                    return symbol
                })
        }
    })
}

/**
 * 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 {array} The HTML for the navigation sidebar.
 */
function buildNav(members) {
    var nav = []
    var seen = {}
    var seenTutorials = {}

    nav.push(buildNavLink('home', '<a href="index.html">Home</a>'))

    nav = nav.concat(buildMemberNav(members.tutorials, "Tutorials", seenTutorials, linktoTutorial))
    nav = nav.concat(buildMemberNav(members.classes, "Classes", seen, linkto))
    nav = nav.concat(buildMemberNav(members.modules, "Modules", {}, linkto))
    nav = nav.concat(buildMemberNav(members.externals, "Externals", seen, linktoExternal))
    nav = nav.concat(buildMemberNav(members.events, "Events", seen, linkto))
    nav = nav.concat(buildMemberNav(members.namespaces, "Namespaces", seen, linkto))
    nav = nav.concat(buildMemberNav(members.mixins, "Mixins", seen, linkto))
    nav = nav.concat(buildMemberNav(members.interfaces, "Interfaces", seen, linkto))

    if (members.globals.length) {
        nav.push(buildNavHeading(linkto('global', 'Globals')))

        members.globals.forEach(function(item) {
            if (item.kind !== "typedef" && !hasOwnProp.call(seen, item.longname)) {
                nav.push(buildNavItem(buildNavType(item.kind, linkto(item.longname, item.name))))
            }

            seen[item.longname] = true
        })
    }

    return nav.join('')
}

function buildMemberNav(items, itemHeading, itemsSeen, linktoFn) {
    var nav = []
    var conf = env.conf.templates || {}

    conf.default = conf.default || {}

    if (items && items.length) {
        var itemsNav = ""

        nav.push(buildNavHeading(itemHeading))

        items.forEach(function(item) {
            var methods = find({
                kind: "function",
                memberof: item.longname
            })
            var members = find({
                kind: "member",
                memberof: item.longname
            })
            var displayName

            if (!hasOwnProp.call(item, "longname")) {
                nav.push(buildNavItem(linkfoFn('', item.name)))
                return
            }

            if (!hasOwnProp.call(itemsSeen, item.longname)) {
                if (!!conf.default.useLongnameInNav) {
                    displayName = item.longname

                    if (conf.default.useLongnameInNav > 0 && conf.default.useLongnameInNav !== true) {
                        var num = conf.default.useLongnameInNav
                        var cropped = item.longname.split(".").slice(-num).join(".")
                        if (cropped !== displayName) {
                            displayName = "..." + cropped
                        }
                    }
                } else {
                    displayName = item.name
                }

                displayName = displayName.replace(/^module:/g, "")

                if (itemHeading === 'Tutorials') {
                    nav.push(buildNavItem(linktoFn(item.longname, displayName)))
                } else {
                    nav.push(buildNavHeading(buildNavType(item.kind, linktoFn(item.longname, displayName))))
                }

                if (methods.length) {
                    methods.forEach(function(method) {
                        if (method.inherited && conf.showInheritedInNav === false) {
                            return
                        }

                        nav.push(buildNavItem(buildNavType(method.kind, linkto(method.longname, method.name))))
                    })
                }

                itemsSeen[item.longname] = true
            }
        })
    }

    return nav
}

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

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

/**
 * Helper to generate navigation list link wrapper around navigation links for 
 * locations.
 * 
 * @param {String} linkClass navigation link classname
 * @param {String} linkContent navigation link HTML content
 * @return {String}
 */
function buildNavLink(linkClass, linkContent) {
    return [
        '<li class="nav-link nav-' + linkClass + '-link">',
        linkContent,
        '</li>'
    ].join('')
}

/**
 * Helper to generate navigation list header wrapper around navigation header content
 * for headings and filenames.
 * 
 * @param {String} content navigation header content
 * @return {String}
 */
function buildNavHeading(content) {
    return [
        '<li class="nav-heading">',
        content,
        '</li>'
    ].join('')
}

/**
 * Helper for generating generic navigation wrapper around content passed for 
 * methods, and types.
 * 
 * @param {String} itemContent navigation item content
 * @return {String}
 */
function buildNavItem(itemContent) {
    return [
        '<li class="nav-item">',
        itemContent,
        '</li>'
    ].join('')
}

function buildNavType(type, typeLink) {
    return [
        '<span class="nav-item-type type-' + type + '">',
        type[0].toUpperCase(),
        '</span>',

        '<span class="nav-item-name">',
        typeLink,
        '</span>'
    ].join('')
}

/**
  @param {TAFFY} taffyData See <http://taffydb.com/>.
  @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 = 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)
    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*<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 && 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) {
        // 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)
                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

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

    // 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]
            )
        }
    })

    // adds table containers for scrolling through tables on mobile
    function addTableContainers(html) {
        return html
            .replace('<table>', '<div class="table-container"><table>')
            .replace('</table>', '</table></div>');
    }

    // 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>
        html = addTableContainers(html)
        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(
                child.title,
                child,
                helper.tutorialToUrl(child.name)
            )
            saveChildren(child)
        })
    }

    saveChildren(tutorials)
}