publish.js

'use strict'

var doop = require('jsdoc/util/doop')
var env = require('jsdoc/env')
var fs = require('jsdoc/fs')
var helper = require('jsdoc/util/templateHelper')
var logger = require('jsdoc/util/logger')
var path = require('jsdoc/path')
var inline = require('jsdoc/tag/inline');
var taffy = require('taffydb').taffy
var template = require('jsdoc/template')
var util = require('util')
const { getParser } = require('jsdoc/util/markdown')

var bundler = require('./bundler')
const markdownParser = getParser()

var htmlsafe = helper.htmlsafe
var linkto = helper.linkto;
if (env.conf.templates["better-docs"].linkTagToNewTab) {
  //Only override these functions if the configurations request it.
  
  //create a regex that will extract the parts of the link tag
  const linkRegex = new RegExp(/^.*\{@link\s?([^\s]+)[\s+]?(.+)?.*\}.*/);
  
  //Parse the tag into it's constituant parts
  const parseLink = (longname) => {
    let matches = linkRegex.exec(longname);
    let text = longname;
    let link = longname;
    let external = false;
    //will only operate on @link tags
    if(matches && matches.length > 1){
        text = matches[1].trim();
        link = matches[1].trim();
        
        //UNescape URL's that got escaped (inside a <code>?) and now look like http(s):\\/\\/
        if((/(http|ftp)s?:/).test(longname)){
          external = true;
          link = link.replace(text, text.replace(/\\\\\//ig, '/'));
        }
        if(matches[2] && matches[2].trim()){
          text = matches[2].trim();
        }
    }
    return {
      text: text,
      link: link,
      external: external,
      inline: inline.isInlineTag(longname)
    };
  };
  const origLinkto = helper.linkto;
  //Override this function so we can automatically open inline link tags to URL's in a new tab
  linkto = helper.linkto = function(longname, linkText, cssClass, fragmentId){
    let parsed = parseLink(longname);
    
    if(parsed.inline && parsed.external){
      //This is an external link, so let's add a target to the anchor so it will open in another window
      return util.format('<a target="_new" href="%s"%s>%s</a>',
        encodeURI(parsed.link),
        cssClass ? util.format(' class="%s"', cssClass) : '',
        htmlsafe(parsed.text)
      );
    }else{
      if(!linkText && parsed.text && parsed.text != longname){
        linkText = parsed.text;
      }
      let link = longname;
      if(parsed.link && parsed.link != longname){
        link = parsed.link;
      }
      let rtn = origLinkto(link, linkText, cssClass, fragmentId);
      
      let skip = [
        'null',
        'object',
        'string',
        'bool',
        'boolean',
        'function',
        'int',
        'float',
        'number',
        'undefined',
        'promise',
        '*',
        'array',
        'uint8array',
        'arraybufferview',
        'arraybuffer',
        'date',
        'enum',
        'error',
      ];
      
      if(skip.indexOf(longname.toLowerCase()) < 0 && rtn.indexOf('<a') < 0){
        let found=false;
        let types = [];
        if(longname.indexOf('.<') >= 0){
          let matches = (new RegExp(/^(.*).<\(?(.*)[\)?]>/)).exec(longname);
          if(matches && matches.length >= 1){
            if(matches.length >= 2){
              types = matches[2].split('|');
              Object.keys(types).forEach(key => types[key] = types[key].trim());
            }
            if(matches[1].trim()){
              types.unshift(matches[1].trim());
            }
          }
        }
        if(types.length <= 0){
          skip.forEach(type => {
            if('Array.<'+type+'>' == longname){
              found=true;
            }
          });
          if(!found){
            console.log('Invalid link to '+longname, linkText);
          }
        }else{
          types.forEach(type => {
            if(skip.indexOf(type.toLowerCase()) < 0){
              console.log('Invalid link to '+type+' for '+longname, linkText);
            }
          });
        }
        
      }
      
      return rtn;
    }
  };
  //save the original resolveLinks so we can use it after we are done with our alterations
  const resolveLinks = helper.resolveLinks;
  var visited=[];
  //replace the inline tag with an actual link
  const doReplace = (string, {completeTag, text, tag}) => {
    let tagIndex = string.indexOf(completeTag);
    if(visited.indexOf(tagIndex) < 0){
      visited.push(tagIndex);
      let parsed = parseLink(completeTag);
      //Only operate on external links, and let the original resolveLinks handle the others later.
      if(parsed.external){
        let linkText = parsed.text && parsed.text != completeTag ? parsed.text : null;
        let theLink = linkto(completeTag, linkText);
    
        return string.replace( completeTag, theLink );
      }else{
        //if we return an unaltered string, then the processing of inline link tags will stop
        //so we'll add a space to the end, and then remove them before calling the original resolveLinks
        return string+' ';
      }
    }else{
      //we don't want to get stuck in a loop continuously trying to parse the same tag
      //but we can't return the same string or we'll never visit subsequent links
      //so we'll replace the tag with an unknown tag, which will be put back to a link AFTER we've
      //processed the whole file.

      return string.replace( completeTag, completeTag.replace('{@'+tag, '{@betterdocsreplaced'+tag) );
    }
  };
  const restoreBetterDocsReplaced = (string, {completeTag, text, tag}) => {
    let type = tag.replace('betterdocsreplaced','');
    return string.replace( completeTag, completeTag.replace('{@'+tag, '{@'+type) );
  };
  
  helper.resolveLinks = string => {
    //let's handle the link tags that we are going to operate on
    let processors = {
      link: doReplace,
      linkcode: doReplace,
      linkplain: doReplace,
    };
    string = inline.replaceInlineTags(string, processors).newString;
    
    //now let's put back the betterdocsreplaced tags that we added in doReplace
    let betterDocsProcessors = {};
    Object.keys(processors).forEach(name => {
      betterDocsProcessors['betterdocsreplaced'+name] = restoreBetterDocsReplaced;
    });
    string = inline.replaceInlineTags(string, betterDocsProcessors).newString;
    
    //Empty our visited so we're ready for the next file.
    visited=[];
    //Now let the original resolveLinks handle whatever we didn't
    //doReplace may have added spaces to the end of the string, so we'll remove them with a trim()
    return resolveLinks(string.trim());
  };
}

var resolveAuthorLinks = helper.resolveAuthorLinks
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) {
  var url

  if ( !/^(#.+)/.test(hash) ) {
    return hash
  }

  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
  }
  // 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)
  
  //For the @lifecycle tag when using the lifecycle plugin
  if(f.hasOwnProperty('lifecycle') && f.lifecycle){
    attribs.push('React Lifecycle');
  }
  
  //For the @renders tag when using the lifecycle plugin
  if(f.hasOwnProperty('renders') && f.renders){
    attribs.push('Causes Render');
  }
  
  var attribsString = buildAttribsString(attribs)

  f.attribs = util.format('<span class="type-signature">%s</span>', attribsString)
  f.rawAttribs = attribs
}

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(title, subtitle, docs, filename, resolveLinks) {
  var docData
  var html
  var outpath

  resolveLinks = resolveLinks !== false

  docData = {
    env: env,
    title: title,
    subtitle: subtitle,
    docs: docs
  }

  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(sourceFiles[file].shortened, 'Source', [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)
  })

  modules.forEach(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
        })
    }
  })
}

function buildMemberNav(items, itemHeading, itemsSeen, linktoFn) {
  const subCategories = items.reduce((memo, item) => {
    const subCategory = item.subCategory || ''
    memo[subCategory] = memo[subCategory] || []
    return {
      ...memo,
      [subCategory]: [...memo[subCategory], item]
    }
  }, {})

  const subCategoryNames = Object.keys(subCategories)
    
  var nav = ''

  subCategoryNames.forEach((subCategoryName) => {
    const subCategoryItems = subCategories[subCategoryName]
    if (subCategoryItems.length) {
      var itemsNav = ''
    
      subCategoryItems.forEach(function(item) {
        var displayName
    
        if ( !hasOwnProp.call(item, 'longname') ) {
          itemsNav += '<li>' + linktoFn('', item.name) + '</li>'
        }
        else if ( !hasOwnProp.call(itemsSeen, item.longname) ) {
          if (env.conf.templates.default.useLongnameInNav) {
            displayName = item.longname
          } else {
            displayName = item.name
          }
          itemsNav += '<li>' + linktoFn(item.longname, displayName.replace(/\b(module|event):/g, ''))

          if (item.children && item.children.length) {
            itemsNav += '<ul>'
            item.children.forEach(child => {
              if (env.conf.templates.default.useLongnameInNav) {
                displayName = child.longname
              } else {
                displayName = child.name
              }
              itemsNav += '<li>' + linktoFn(child.longname, displayName.replace(/\b(module|event):/g, '')) + '</li>'
            })
            itemsNav += '</ul>'
          }

          itemsNav += '</li>'
    
          itemsSeen[item.longname] = true
        }
      })
            
      if (itemsNav !== '') {
        var heading = itemHeading
        if (subCategoryName) {
          heading = heading + ' / ' + subCategoryName
        }
        var search = env.conf.templates && env.conf.templates.search;

        nav += '<h3>' + heading + '</h3>'

        if(search && heading === "Hooks API") {
          nav += `
          <div class="search-wrapper">
              <input id="search" type="text" placeholder="Search Hooks..." class="input">
          </div>`;
        }
          
        nav += '<ul>' + itemsNav + '</ul>'

      }
    }
  })

  return nav
}

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

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

function buildGroupNav (members, title) {
  if (env.conf.templates.betterDocs.useNestedCategories) {
    return buildGroupNavNested(members, title);
  }
  var globalNav
  var seenTutorials = {}
  var nav = ''
  var seen = {}
  nav += '<div class="category">'
  if (title) {
    nav += '<h2>' + title + '</h2>'
  }

  if (members.globals && members.globals.length) {
    globalNav = ''

    members.globals.forEach(function(g) {
      if ( 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
      //nav += '<h3>' + linkto('global', globalStr) + '</h3>'
    }
    else {
      nav += '<h3>' + globalStr + '</h3><ul>' + globalNav + '</ul>'
    }
  }

  nav += buildMemberNav(members.tutorials || [], 'Tutorials', seenTutorials, linktoTutorial)
  nav += buildMemberNav(members.modules || [], 'Modules', {}, linkto)
  nav += buildMemberNav(members.externals || [], 'Externals', seen, linktoExternal)
  nav += buildMemberNav(members.namespaces || [], 'Namespaces', seen, linkto)
  nav += buildMemberNav(members.classes || [], 'Hooks API', seen, linkto)
  nav += buildMemberNav(members.interfaces || [], 'Interfaces', seen, linkto)
  nav += buildMemberNav(members.events || [], 'Events', seen, linkto)
  nav += buildMemberNav(members.mixins || [], 'Mixins', seen, linkto)
  nav += buildMemberNav(members.components || [], 'Components', seen, linkto)  
  nav += '</div>'
  return nav
}

/**
 * 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.components
 * @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, navTypes = null, betterDocs) {
  const href = betterDocs.landing ? 'docs.html' : 'index.html'
  var nav = `<h3><a href="${href}">Overview</a></h3>`;
  if (env.conf.templates.betterDocs.includeTodoPage) {
    let todoHref = 'Todo.html';
    nav += `<h2><a href="${todoHref}">TODO</a></h2>`;
  }

  nav += `<h3><a href="global.html">Type Definitions</a></h3>`;
  nav += `<h3><a href="styles.html">Global CSS Styles</a></h3>`;
  nav += `<h3><a href="dependencies.html">Dependencies</a></h3>`;

  var categorised = {}
  var rootScope = {}

  var types = navTypes || ['modules', 'externals', 'namespaces', 'classes',
    'components', 'interfaces', 'events', 'mixins', 'globals']
  types.forEach(function(type) {
    if (!members[type]) { return }
    members[type].forEach(function(element) {
      if (element.access && element.access === 'private') {
        return
      }
      if (element.category) {
        if (!categorised[element.category]){ categorised[element.category] = [] }
        if (!categorised[element.category][type]){ categorised[element.category][type] = [] }
        categorised[element.category][type].push(element)
      } else {
        rootScope[type] ? rootScope[type].push(element) : rootScope[type] = [element]
      }
    })
  })
    
  nav += buildGroupNav(rootScope)
  Object.keys(categorised).sort().forEach(function (category) {
    nav += buildGroupNav(categorised[category], category)
  })

  return nav
}

const globalStr = "Type Definitions";
/**
 *
 * Build the navigation for a given set of members which belong to the category defined in the title
 * 
 * @param {object} items The members that will be used to create the sidebar.
 * @param {array<object>} items.classes
 * @param {array<object>} items.components
 * @param {array<object>} items.externals
 * @param {array<object>} items.globals
 * @param {array<object>} items.mixins
 * @param {array<object>} items.modules
 * @param {array<object>} items.namespaces
 * @param {array<object>} items.tutorials
 * @param {array<object>} items.events
 * @param {array<object>} items.interfaces
 * @param {String} title The name of the group to build the navigation for
 * 
 * @return {string} The HTML for a groups navigation in the sidebar.
 * 
 */
function buildGroupNavNested (members, title) {
  var globalNav;
  var seenTutorials = {};
  var nav = '';
  var seen = {};
  //define our types so we can just loop through them
  let types = {
    tutorials: {name: 'Tutorials', seen: seenTutorials, link: linktoTutorial},
    modules: {name: 'Modules', seen: {}, link: linkto},
    externals: {name: 'Externals', seen: seen, link: linktoExternal},
    namespaces: {name: 'Namespaces', seen: seen, link: linkto},
    classes: {name: 'Hooks', seen: seen, link: linkto},
    interfaces: {name: 'Interfaces', seen: seen, link: linkto},
    events: {name: 'Events', seen: seen, link: linkto},
    mixins: {name: 'Mixins', seen: seen, link: linkto},
    components: {name: 'Components', seen: seen, link: linkto},
    globals: {name: globalStr, seen: seen, link: linkto},
  };
  //organize the members according to their category and then type
  let categorized = {};
  Object.keys(types).forEach(type => {
    if(members[type]){
      members[type].forEach(member => {
        let subCat = member.subCategory || '';
        categorized[subCat] = categorized[subCat] || {};
        if(type != 'events' || (type == 'events' && !member.memberof)){
          categorized[subCat][type] = categorized[subCat][type] || [];
          categorized[subCat][type].push(member);
        }
      });
    }
  });
  
  //determine if this subcategory list is a mixed list of subcategories and members
  
  
  
  let categorizedKeys = Object.keys(categorized);
  let hasEmptySubcats=categorizedKeys.indexOf('') >= 0;
  let hasNonEmptySubcats=(hasEmptySubcats && categorizedKeys.length > 1) || (!hasEmptySubcats && categorizedKeys.length > 0);
  categorizedKeys.forEach(subCat => {
    let typeKeys = Object.keys(categorized[subCat]);
  });
  
  
  
  nav += "\n\n<div class=\"category"+(title ? ' nested' : '')+"\">\n";
  if (title) {
    if (env.conf.templates.betterDocs.useNavFolding) {
      nav += "  <a href=\"javascript:void(0);\" class=\"category-opener\" data-cat=\""+title+"\">\n"+
      "    <i class=\"fas fa-caret-"+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'right' : 'down')+"\"></i>\n  ";
    }
    nav += "  <h2>" + title + "</h2>\n";
    if (env.conf.templates.betterDocs.useNavFolding) {
      nav += "  </a>\n";
    }
    nav += '  <ul class="subcategories';
    if (env.conf.templates.betterDocs.useNavFolding) {
      nav += ' '+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'closed' : 'opened');
    }
    if(hasEmptySubcats && hasNonEmptySubcats){
      nav+= ' is-mixed';
    }
    
    nav += "\" data-cat=\""+title+"\">\n";
  }
  
  
  categorizedKeys.forEach(subCat => {
    
    if(title && subCat){
      if (env.conf.templates.betterDocs.useNavFolding) {
        nav += "    <li class=\""+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'closed' : 'opened')+"\" data-cat=\""+title+"\">\n"+
        "      <a href=\"javascript:void(0);\" class=\"category-opener\" data-subcat=\""+subCat+"\">\n"+
        "        <i class=\"fas fa-caret-"+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'right' : 'down')+"\"></i>\n"+
        "        <h3 class=\"subCat\">"+subCat+"</h3>\n"+
        "      </a>\n"+
        "      <ul class=\"types\">\n";
      }else{
        nav += "    <li>\n"+
        "      <h3>"+subCat+"</h3>\n"+
        "      <ul>\n";
      }
    }
    let typeKeys = Object.keys(categorized[subCat]);
    typeKeys.forEach(type => {
      if(typeKeys.length > 1){
        nav += title ? "        <li data-subcat=\""+subCat+"\">\n" : '';
      }
      nav += buildMemberNavNested(categorized[subCat][type] || [], types[type].name, types[type].seen, types[type].link, title, subCat, !title || typeKeys.length > 1);
      if(typeKeys.length > 1){
        nav += title ? "        </li><!-- /members for '"+subCat+"\"' -->\n" : '';
      }
    });
    if(title && subCat){
      nav += "      </ul> <!-- /types for subcategory '"+subCat+"' -->\n"+
      "    </li>\n";
    }
    
  });
  if(title){
    nav += "  </ul><!-- /subcategories for '"+title+"' -->\n"+
    "</div>";
  }
  
  //if (members.globals && members.globals.length) {
  //  globalNav = ''
  //
  //  members.globals.forEach(function(g) {
  //    if ( 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
  //    nav += '<h3>' + linkto('global', 'Global') + '</h3>'
  //  }
  //  else {
  //    if (env.conf.templates.betterDocs.useNavFolding) {
  //      nav += ''+
  //      '<div class="member-container '+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'closed' : 'opened')+'">'+
  //        '<a href="javascript:void(0);" class="member-opener" data-member="Global">'+
  //        '<i class="fas fa-caret-'+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'right' : 'down')+'"></i>'+
  //        '<h3>Global</h3><ul data-member="Global">' + globalNav + '</ul>';
  //    }else{
  //      nav += '<h3>Global</h3><ul>' + globalNav + '</ul>'
  //    }
  //    
  //    
  //    
  //    
  //    
  //  }
  //}
  
  return nav;
}

/**
 * Build the memberNav with the subcategories nested under the categories, and the
 * member types nested under the subcategories
 *
 * @param {array<object>}   items             A list of members for a specific category, subcategory, and member type
 * @param {string}          itemHeading       The name of the member type heading for these items
 * @param {object}          itemsSeen         An object containing the members that have already been placed in the navigation indexed by the longname
 * @param {function}        linktoFn          A function that is used to build a link to a specific member's page
 * @param {string}          catHeading
 * @param {string}          subCatHeading
 * @param {bool}            useItemHeading    Determines if the items should use a heading. Set to false when not nesting items in their itemHeading.
 */
function buildMemberNavNested(items, itemHeading, itemsSeen, linktoFn, catHeading, subCatHeading, useItemHeading) {
  let nav = '';
  if(items){
    if(useItemHeading){
      let hNum = catHeading && subCatHeading ? '4' : '3';
      let heading = "             <h"+hNum+">"+itemHeading+"</h"+hNum+">\n";
      if (env.conf.templates.betterDocs.useNavFolding) {
        nav += ''+
        '          <div class="member-container '+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'closed' : 'opened')+'">'+"\n"+
        '            <a href="javascript:void(0);" class="member-opener" data-member="'+itemHeading+'">'+"\n"+
        '              <i class="fas fa-caret-'+(env.conf.templates.betterDocs.foldingDefaultClosed ? 'right' : 'down')+'"></i>'+"\n";
      }
      nav += heading;
      if (env.conf.templates.betterDocs.useNavFolding) {
        nav += "            </a>\n";
      }
      nav += '            <ul data-member="'+itemHeading+'">'+"\n";
    }
    items.forEach(item => {
      nav += "              <li>";
      let displayName;
      if ( !hasOwnProp.call(item, 'longname') ) {
        nav += linktoFn('', item.name);
      }else if ( !hasOwnProp.call(itemsSeen, item.longname) ) {
        if (env.conf.templates.default.useLongnameInNav) {
          displayName = item.longname;
        } else {
          displayName = item.name;
        }
        nav += linktoFn(item.longname, displayName.replace(/\b(module|event):/g, ''));
        itemsSeen[item.longname] = true;
      }
      nav += "</li>\n";
    });
    if(useItemHeading){
      nav += "            </ul>\n";
    }
    if(useItemHeading && env.conf.templates.betterDocs.useNavFolding){
      nav += "          </div>\n";
    }
  }
  return nav;
}

/**
    @param {TAFFY} taffyData See <http://taffydb.com/>.
    @param {object} opts
    @param {Tutorial} tutorials
 */
exports.publish = function(taffyData, opts, tutorials) {
  var classes
  var conf
  var externals
  var files
  var fromDir
  var globalUrl
  var indexUrl
  var interfaces
  var components
  var members
  var mixins
  var modules
  var namespaces
  var outputSourceFiles
  var packageInfo
  var packages
  var sourceFilePaths = []
  var sourceFiles = {}
  var staticFileFilter
  var staticFilePaths
  var staticFiles
  var staticFileScanner
  var templatePath

  data = taffyData

  conf = env.conf.templates || {}
  conf.default = conf.default || {}
  conf.betterDocs = conf.betterDocs || conf['better-docs'] || {}

  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
  indexUrl = helper.getUniqueFilename('index')
  // don't call registerLink() on this one! 'index' is also a valid longname

  globalUrl = helper.getUniqueFilename('global')
  helper.registerLink('global', globalUrl)

  var stylesUrl = helper.getUniqueFilename('styles')
  helper.registerLink('styles', stylesUrl)

  var dependenciesUrl = helper.getUniqueFilename('dependencies')
  helper.registerLink('dependencies', dependenciesUrl)

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

  data().each(function(doclet) {
    var sourcePath

    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
        }
      })
    }
    if (doclet.see) {
      doclet.see.forEach(function(seeItem, i) {
        doclet.see[i] = hashToLink(doclet, seeItem)
      })
    }

    // build a list of source files
    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
  packageInfo = ( find({kind: 'package'}) || [] )[0]
  if (packageInfo && packageInfo.name) {
    const dirVersion = '1.0.0'
    outdir = path.join( outdir, packageInfo.name, dirVersion )
  }
  fs.mkPath(outdir)

  // copy the template's static files to outdir
  fromDir = path.join(templatePath, 'static')
  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
  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

      filePath = path.resolve(env.pwd, filePath)
      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 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 = 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'
    }
  })

  view.smallHeader = !conf.betterDocs.navButtons

  members = helper.getMembers(data)
  if (opts.tutorials) {
    // sort tutorials
    try {
      const tutorialsFile = JSON.parse(fs.readFileSync(`${opts.tutorials}/tutorials.json`))
      members.tutorials = Object.keys(tutorialsFile).map(key => tutorials._tutorials[key])
      view.smallHeader = false
    } catch (error) {
      // tutorials.json doesn't exist
      if (error.code !== 'ENOENT') {
        throw error
      }
      members.tutorials = tutorials.children
    }
        
  } else {
    members.tutorials = tutorials.children
  }
  view.tutorials = members.tutorials
  members.components = helper.find(data, {kind: 'class', component: {isUndefined: false}})
  members.classes = helper.find(data, {kind: 'class', component: {isUndefined: true}})

  // output pretty-printed source files by default
  outputSourceFiles = conf.default && conf.default.outputSourceFiles !== false

  // add template helpers
  view.find = find
  view.linkto = linkto
  view.resolveAuthorLinks = resolveAuthorLinks
  view.tutorialToUrl = helper.tutorialToUrl
  view.tutoriallink = tutoriallink;
  view.htmlsafe = htmlsafe
  view.outputSourceFiles = outputSourceFiles

  // once for all
  view.nav = buildNav(members, null, conf.betterDocs)
  
  view.tutorialsNav = buildNav(members, ['tutorials'], conf.betterDocs)

  bundler(members.components, outdir, conf)
  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("", "", [{kind: 'globalobj'}], globalUrl) }

  // index page displays information from package.json and lists files
  files = find({kind: 'file'})
  packages = find({kind: 'package'})
  generate('Overview', '',
    packages.concat(
      [{
        kind: 'mainpage',
        readme: opts.readme,
        longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'
      }]
    ).concat(files), indexUrl)

  if (env.conf.templates.betterDocs.includeTodoPage) {
    //Generate the todo page
    let docs = {};
    //Gather all the members that have a TODO
    data().each(function(member) {
      if(member && Object.keys(member).indexOf('todo') >= 0){
        if(!docs.hasOwnProperty(member.meta.shortpath)){
          docs[member.meta.shortpath] = {
            shortpath: member.meta.shortpath,
            path: member.meta.path,
            filepath: path.join(member.meta.path, member.meta.filename),
            members: []
          }
        }
        docs[member.meta.shortpath].members.push(member);
      }
    });

    generate('TODO', '', [{kind: 'todo', docs:docs}], helper.getUniqueFilename('Todo'));
  }

  // generate('Styles', '',
  //   [{
  //     kind: 'stylespage',
  //     // readme: opts.readme,
  //     longname: "Styles"
  //   }]
  //  , stylesUrl)

  // set up the lists that we'll use to generate pages
  classes = taffy(members.classes)
  modules = taffy(members.modules)
  namespaces = taffy(members.namespaces)
  mixins = taffy(members.mixins)
  externals = taffy(members.externals)
  interfaces = taffy(members.interfaces)
  components = taffy(members.components)

  Object.keys(helper.longnameToUrl).forEach(function(longname) {
    var myClasses = helper.find(classes, {longname: longname})
    var myExternals = helper.find(externals, {longname: longname})
    var myInterfaces = helper.find(interfaces, {longname: longname})
    var myMixins = helper.find(mixins, {longname: longname})
    var myModules = helper.find(modules, {longname: longname})
    var myNamespaces = helper.find(namespaces, {longname: longname})
    var myComponents = helper.find(components, {longname: longname})

    if (myModules.length) {
      generate(myModules[0].name, 'Module', myModules,  helper.longnameToUrl[longname])
    }

    if (myClasses.length) {
      generate(myClasses[0].name, 'Class', myClasses, helper.longnameToUrl[longname])
    }

    if (myNamespaces.length) {
      generate(myNamespaces[0].name, 'Namespace', myNamespaces, helper.longnameToUrl[longname])
    }

    if (myMixins.length) {
      generate(myMixins[0].name, 'Mixin', myMixins, helper.longnameToUrl[longname])
    }

    if (myExternals.length) {
      generate(myExternals[0].name, 'External', myExternals, helper.longnameToUrl[longname])
    }

    if (myInterfaces.length) {
      generate(myInterfaces[0].name, 'Interface', myInterfaces, helper.longnameToUrl[longname])
    }

    if (myComponents.length) {
      generate(myComponents[0].name, 'Components', myComponents, helper.longnameToUrl[longname])
    }
  })

  // TODO: move the tutorial functions to templateHelper.js
  function generateTutorial(title, subtitle, tutorial, filename) {
    var tutorialData = {
      title: title,
      subtitle: subtitle,
      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(child.title, 'Tutorial', child, helper.tutorialToUrl(child.name))
      saveChildren(child)
    })
  }

  saveChildren(tutorials)

  function generateStyles() {

    const stylesFile = fs.readFileSync(opts.styles);
    
    var tutorialData = {
      title: "Global CSS Styles",
      subtitle: '',
      header: "Global CSS Styles",
      code: stylesFile
    }

    var stylesPath = path.join(outdir, stylesUrl)
    var html = view.render('stylespage.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(stylesPath, html, 'utf8')
  }

  generateStyles();

  function generateDependencies() {

    const packageFile = JSON.parse(fs.readFileSync(opts.package));
    
    var tutorialData = {
      title: "Dependencies",
      subtitle: '',
      header: "Dependencies",
      dependencies: packageFile.dependencies
    }

    var dependenciesPath = path.join(outdir, dependenciesUrl)
    var html = view.render('dependencies.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(dependenciesPath, html, 'utf8')
  }

  generateDependencies();

  function saveLandingPage() {
    const content = fs.readFileSync(conf.betterDocs.landing, 'utf8')
        
    var landingPageData = {
      title: 'Overview',
      content,
    }

    var homePath = path.join(outdir, 'index.html')
    var docsPath = path.join(outdir, 'docs.html')

    fs.renameSync(homePath, docsPath)
        
    view.layout = 'landing.tmpl'
    var html = view.render('content.tmpl', landingPageData)

    // yes, you can use {@link} in tutorials too!
    html = helper.resolveLinks(html) // turn {@link foo} into <a href="foodoc.html">foo</a>

    fs.writeFileSync(homePath, html, 'utf8')

  }

  if (conf.betterDocs.landing) {
    saveLandingPage()
  }
}