better-docs
Version:
841 lines (687 loc) • 24.5 kB
JavaScript
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 taffy = require('@jsdoc/salty').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
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 = '…' + 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( ' → %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)
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
}
nav += '<h3>' + heading + '</h3><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) {
var globalNav
var seenTutorials = {}
var nav = ''
var seen = {}
nav += '<div class="category">'
if (title) {
nav += '<h2>' + title + '</h2>'
}
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 || [], 'Classes', 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)
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 {
nav += '<h3>Global</h3><ul>' + globalNav + '</ul>'
}
}
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 = navTypes ? '' : `<h2><a href="${href}">Documentation</a></h2>`
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
}
/**
@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)
// 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) {
outdir = path.join( outdir, packageInfo.name, (packageInfo.version || '') )
}
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('Global', null, [{kind: 'globalobj'}], globalUrl) }
// index page displays information from package.json and lists files
files = find({kind: 'file'})
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
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 saveLandingPage() {
const content = fs.readFileSync(conf.betterDocs.landing, 'utf8')
var landingPageData = {
title: 'Home',
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()
}
}