From ef9c44518a6959bc4431ba966abd55a839bc4d63 Mon Sep 17 00:00:00 2001 From: Hubert Argasinski Date: Sun, 11 Dec 2016 01:34:03 -0500 Subject: docs: added searching aliases (see #1339) --- support/jsdoc/jsdoc-custom.js | 22 +++++++++--- support/jsdoc/jsdoc-fix-html.js | 29 +-------------- support/jsdoc/theme/publish.js | 69 +++++++++++++++++++++++++++++++----- support/jsdoc/theme/tmpl/layout.tmpl | 7 ++-- 4 files changed, 82 insertions(+), 45 deletions(-) diff --git a/support/jsdoc/jsdoc-custom.js b/support/jsdoc/jsdoc-custom.js index fc22991..b101444 100644 --- a/support/jsdoc/jsdoc-custom.js +++ b/support/jsdoc/jsdoc-custom.js @@ -1,4 +1,8 @@ /* eslint no-undef: "off" */ +if (typeof setImmediate !== 'function' && typeof async === 'object') { + setImmediate = async.setImmediate; +} + $(function initSearchBar() { function matchSubstrs(methodName) { var tokens = []; @@ -94,12 +98,20 @@ $(function initSearchBar() { // handle source files } else if (suggestion.indexOf('.html') !== -1) { location.href = host + suggestion; - // handle searching from one of the source files or the home page - } else if (currentPage !== 'docs.html') { - location.href = host + 'docs.html#' + suggestion; } else { - var $el = document.getElementById(suggestion); - $('#main-container').animate({ scrollTop: $el.offsetTop - 60 }, 500); + var parenIndex = suggestion.indexOf('('); + if (parenIndex !== -1) { + suggestion = suggestion.substring(0, parenIndex-1); + } + + // handle searching from one of the source files or the home page + if (currentPage !== 'docs.html') { + location.href = host + 'docs.html#' + suggestion; + } else { + var $el = document.getElementById(suggestion); + $('#main-container').animate({ scrollTop: $el.offsetTop - 60 }, 500); + location.hash = '#'+suggestion; + } } }); diff --git a/support/jsdoc/jsdoc-fix-html.js b/support/jsdoc/jsdoc-fix-html.js index 067a212..15234a0 100644 --- a/support/jsdoc/jsdoc-fix-html.js +++ b/support/jsdoc/jsdoc-fix-html.js @@ -42,29 +42,6 @@ function extractModuleFiles(files) { }); } -function getSearchableInfo($page, callback) { - var $sourceLinks = $page.find('a[href$=".js.html"]'); - var sourceFiles = $sourceLinks.map(function() { - return $(this).attr('href'); - }).toArray().sort(); - - var $methodLinks = $page.find('nav').find('a'); - var methods = $methodLinks.map(function() { - var methodName = $(this).text(); - return (methodName === 'Home' ? null : methodName); - }).toArray().sort(); - - fs.mkdirsSync(path.join(docsDir, 'data')); - async.parallel([ - function(fileCallback) { - fs.writeJson(path.join(docsDir, 'data/sourceFiles.json'), sourceFiles, fileCallback); - }, - function(fileCallback) { - fs.writeJson(path.join(docsDir, 'data/methodNames.json'), methods, fileCallback); - } - ], callback); -} - function combineFakeModules(files, callback) { var moduleFiles = extractModuleFiles(files); @@ -86,11 +63,7 @@ function combineFakeModules(files, callback) { }); }, function(err) { if (err) return callback(err); - - getSearchableInfo($mainPage, function(err) { - if (err) return callback(err); - generateHTMLFile(path.join(docsDir, docFilename), $mainPage, callback); - }); + generateHTMLFile(path.join(docsDir, docFilename), $mainPage, callback); }); }); } diff --git a/support/jsdoc/theme/publish.js b/support/jsdoc/theme/publish.js index fbfd614..c492f39 100644 --- a/support/jsdoc/theme/publish.js +++ b/support/jsdoc/theme/publish.js @@ -2,7 +2,8 @@ 'use strict'; var doop = require('jsdoc/util/doop'); -var fs = require('jsdoc/fs'); +var fs = require('jsdoc/fs'); // jsdoc/fs offer non-standard functions (mkPath) +var fsExtra = require('fs-extra'); var helper = require('jsdoc/util/templateHelper'); var logger = require('jsdoc/util/logger'); var path = require('jsdoc/path'); @@ -226,10 +227,12 @@ function generate(type, title, docs, filename, resolveLinks) { function generateSourceFiles(sourceFiles, encoding) { encoding = encoding || 'utf8'; + var sourceFilenames = []; 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); + sourceFilenames.push(sourceOutfile); helper.registerLink(sourceFiles[file].shortened, sourceOutfile); try { @@ -241,9 +244,9 @@ function generateSourceFiles(sourceFiles, encoding) { catch(e) { logger.error('Error while generating source file %s: %s', file, e.message); } - generate('Source', sourceFiles[file].shortened, [source], sourceOutfile, false); }); + return sourceFilenames; } /** @@ -384,6 +387,40 @@ function buildNav(members) { return nav; } +/** + Sorts an array of strings alphabetically + @param {Array} strArr - Array of strings to sort + @return {Array} The sorted array + */ +function sortStrs(strArr) { + return strArr.sort(function(s1, s2) { + var lowerCaseS1 = s1.toLowerCase(); + var lowerCaseS2 = s2.toLowerCase(); + + if (lowerCaseS1 < lowerCaseS2) { + return -1; + } else if (lowerCaseS1 > lowerCaseS2) { + return 1; + } else { + return 0; + } + }); +} + +/** + Prints into /data a `methodNames.json` and a `sourceFiles.json` + JSON file that contains methods and files that can be searched on the + generated doc site. + @param {Array} methodNames - A list of method names + @param {Array} sourceFilenames - A list of source filenames + */ +function writeSearchData(methodNames, sourceFilenames) { + var dataDir = path.join(outdir, 'data'); + fsExtra.mkdirsSync(dataDir); + fsExtra.writeJsonSync(path.join(dataDir, 'methodNames.json'), sortStrs(methodNames), 'utf8'); + fsExtra.writeJsonSync(path.join(dataDir, 'sourceFiles.json'), sortStrs(sourceFilenames), 'utf8'); +} + /** @param {TAFFY} taffyData See . @param {object} opts @@ -537,8 +574,21 @@ exports.publish = function(taffyData, opts, tutorials) { }); // do this after the urls have all been generated + var methodNames = []; data().each(function(doclet) { doclet.ancestors = getAncestorLinks(doclet); + if (doclet.kind === 'function') { + var alias = doclet.alias; + var name = doclet.name; + if (alias) { + if (Array.isArray(alias)) { + alias = alias.join(', '); + } + methodNames.push(name + ` (${alias})`); + } else { + methodNames.push(name); + } + } if (doclet.kind === 'member') { addSignatureTypes(doclet); @@ -556,8 +606,8 @@ exports.publish = function(taffyData, opts, tutorials) { members.tutorials = tutorials.children; // output pretty-printed source files by default - var outputSourceFiles = conf.default && conf.default.outputSourceFiles !== false - ? true + var outputSourceFiles = conf.default && conf.default.outputSourceFiles !== false + ? true : false; // add template helpers @@ -573,12 +623,15 @@ exports.publish = function(taffyData, opts, tutorials) { attachModuleSymbols( find({ longname: {left: 'module:'} }), members.modules ); // generate the pretty-printed source files first so other pages can link to them + var sourceFilenames = []; if (outputSourceFiles) { - generateSourceFiles(sourceFiles, opts.encoding); + sourceFilenames = generateSourceFiles(sourceFiles, opts.encoding); } - if (members.globals.length) { - generate('', 'Global', [{kind: 'globalobj'}], globalUrl); + writeSearchData(methodNames, sourceFilenames); + + if (members.globals.length) { + generate('', 'Global', [{kind: 'globalobj'}], globalUrl); } // index page displays information from package.json and lists files @@ -655,6 +708,6 @@ exports.publish = function(taffyData, opts, tutorials) { saveChildren(child); }); } - + saveChildren(tutorials); }; diff --git a/support/jsdoc/theme/tmpl/layout.tmpl b/support/jsdoc/theme/tmpl/layout.tmpl index 912097d..631efa4 100644 --- a/support/jsdoc/theme/tmpl/layout.tmpl +++ b/support/jsdoc/theme/tmpl/layout.tmpl @@ -11,7 +11,7 @@ - +