@edx/frontend-platform 4.6.0 → 4.6.2

package/docs/template/edx/publish.js

@@ -0,0 +1,713 @@
+const doop = require('jsdoc/util/doop');
+const env = require('jsdoc/env');
+const fs = require('jsdoc/fs');
+const helper = require('jsdoc/util/templateHelper');
+const logger = require('jsdoc/util/logger');
+const path = require('jsdoc/path');
+const template = require('jsdoc/template');
+const util = require('util');
+
+const htmlsafe = helper.htmlsafe;
+const linkto = helper.linkto;
+const resolveAuthorLinks = helper.resolveAuthorLinks;
+const hasOwnProp = Object.prototype.hasOwnProperty;
+
+let data;
+let view;
+
+let 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) {
+    let url;
+
+    if ( !/^(#.+)/.test(hash) ) {
+        return hash;
+    }
+
+    url = helper.createLink(doclet);
+    url = url.replace(/(#.+|$)/, hash);
+
+    return `<a href="${url}">${hash}</a>`;
+}
+
+function needsSignature({kind, type, meta}) {
+    let needsSig = false;
+
+    // function and class definitions always get a signature
+    if (kind === 'function' || kind === 'class') {
+        needsSig = true;
+    }
+    // typedefs that contain functions get a signature, too
+    else if (kind === 'typedef' && type && type.names &&
+        type.names.length) {
+        for (let i = 0, l = type.names.length; i < l; i++) {
+            if (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 (kind === 'namespace' && meta && meta.code &&
+        meta.code.type && meta.code.type.match(/[Ff]unction/)) {
+        needsSig = true;
+    }
+
+    return needsSig;
+}
+
+function getSignatureAttributes({optional, nullable}) {
+    const attributes = [];
+
+    if (optional) {
+        attributes.push('opt');
+    }
+
+    if (nullable === true) {
+        attributes.push('nullable');
+    }
+    else if (nullable === false) {
+        attributes.push('non-null');
+    }
+
+    return attributes;
+}
+
+function updateItemName(item) {
+    const attributes = getSignatureAttributes(item);
+    let 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(({name}) => name && !name.includes('.')).map(updateItemName);
+}
+
+function buildItemTypeStrings(item) {
+    const types = [];
+
+    if (item && item.type && item.type.names) {
+        item.type.names.forEach(name => {
+            types.push( linkto(name, htmlsafe(name)) );
+        });
+    }
+
+    return types;
+}
+
+function buildAttribsString(attribs) {
+    let attribsString = '';
+
+    if (attribs && attribs.length) {
+        attribsString = htmlsafe( util.format('(%s) ', attribs.join(', ')) );
+    }
+
+    return attribsString;
+}
+
+function addNonParamAttributes(items) {
+    let types = [];
+
+    items.forEach(item => {
+        types = types.concat( buildItemTypeStrings(item) );
+    });
+
+    return types;
+}
+
+function addSignatureParams(f) {
+    const params = f.params ? addParamAttributes(f.params) : [];
+
+    f.signature = util.format( '%s(%s)', (f.signature || ''), params.join(', ') );
+}
+
+function addSignatureReturns(f) {
+    const attribs = [];
+    let attribsString = '';
+    let returnTypes = [];
+    let returnTypesString = '';
+    const 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(item => {
+            helper.getAttribs(item).forEach(attrib => {
+                if (!attribs.includes(attrib)) {
+                    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) {
+    const types = f.type ? buildItemTypeStrings(f) : [];
+
+    f.signature = `${f.signature || ''}<span class="type-signature">${types.length ? ` :${types.join('|')}` : ''}</span>`;
+}
+
+function addAttribs(f) {
+    const attribs = helper.getAttribs(f);
+    const attribsString = buildAttribsString(attribs);
+
+    f.attribs = util.format('<span class="type-signature">%s</span>', attribsString);
+}
+
+function shortenPaths(files, commonPrefix) {
+    Object.keys(files).forEach(file => {
+        files[file].shortened = files[file].resolved.replace(commonPrefix, '')
+            // always use forward slashes
+            .replace(/\\/g, '/');
+    });
+
+    return files;
+}
+
+function getPathFromDoclet({meta}) {
+    if (!meta) {
+        return null;
+    }
+
+    return meta.path && meta.path !== 'null' ?
+        path.join(meta.path, meta.filename) :
+        meta.filename;
+}
+
+function generate(title, docs, filename, { resolveLinks = false, moduleName = '' } = {}) {
+    let docData;
+    let html;
+    let outpath;
+    resolveLinks = resolveLinks !== false;
+
+    docData = {
+        env: env,
+        title: title,
+        docs: docs,
+        moduleName,
+    };
+
+    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 = 'utf8') {
+    Object.keys(sourceFiles).forEach(file => {
+        let source;
+        // links are keyed to the shortened path in each doclet's `meta.shortpath` property
+        const 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);
+    });
+}
+
+/**
+ * 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) {
+    const symbols = {};
+
+    // build a lookup table
+    doclets.forEach(symbol => {
+        symbols[symbol.longname] = symbols[symbol.longname] || [];
+        symbols[symbol.longname].push(symbol);
+    });
+
+    modules.forEach(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(({description, kind}) => description || kind === 'class')
+                .map(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) {
+    let nav = '';
+
+    const renderSubNav = (doclets => {
+        if (!doclets || !doclets.length) return '';
+
+        const renderChild = (doclet) => {
+            return `<li>${linktoFn(doclet.longname, doclet.name)}</li>`;
+        }
+
+        return `
+            <ul class="list-unstyled px-3 pb-4 bg-light">
+                ${doclets.map(renderChild).join('')}
+            </ul>
+        `;
+    });
+
+    if (items.length) {
+        let itemsNav = '';
+
+        items.forEach(item => {
+            let displayName;
+
+            if ( !hasOwnProp.call(item, 'longname') ) {
+                itemsNav += `<li class="nav-item">${linktoFn('', item.name, 'nav-link')}</li>`;
+            }
+            else if ( !hasOwnProp.call(itemsSeen, item.longname) ) {
+                if (env.conf.templates.default.useLongnameInNav) {
+                    displayName = item.longname;
+                } else {
+                    displayName = item.name;
+                }
+
+                itemsNav += `<li class="module-section nav-item ${displayName}">
+                    ${linktoFn(item.longname, displayName.replace(/\b(module|event):/g), 'nav-link font-weight-bold')}
+                    ${renderSubNav(item.children)}
+                </li>`;
+
+                itemsSeen[item.longname] = true;
+            }
+        });
+
+        if (itemsNav !== '') {
+            nav += `<ul class="list-unstyled nav flex-column">${itemsNav}</ul>`;
+        }
+    }
+
+    return nav;
+}
+
+function linktoTutorial(longName, name) {
+    return tutoriallink(name);
+}
+
+function linktoExternal(longName, name) {
+    return linkto(longName, name.replace(/(^"|"$)/g, ''));
+}
+
+/**
+ * Create the navigation sidebar.
+ * @param {object} members The members that will be used to create the sidebar.
+ * @param {array<object>} members.classes
+ * @param {array<object>} members.externals
+ * @param {array<object>} members.globals
+ * @param {array<object>} members.mixins
+ * @param {array<object>} members.modules
+ * @param {array<object>} members.namespaces
+ * @param {array<object>} members.tutorials
+ * @param {array<object>} members.events
+ * @param {array<object>} members.interfaces
+ * @return {string} The HTML for the navigation sidebar.
+ */
+function buildNav(members) {
+    let globalNav;
+    let nav = '<h2><a href="index.html">Home</a></h2>';
+    const seen = {};
+    const seenTutorials = {};
+
+    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.tutorials, 'Tutorials', seenTutorials, linktoTutorial);
+
+    // if (members.globals.length) {
+    //     globalNav = '';
+
+    //     members.globals.forEach(({kind, longname, name}) => {
+    //         if ( kind !== 'typedef' && !hasOwnProp.call(seen, longname) ) {
+    //             globalNav += `<li>${linkto(longname, name)}</li>`;
+    //         }
+    //         seen[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>`;
+    //     }
+    // }
+
+    return nav;
+}
+
+/**
+    @param {object} memberData
+    @param {object} opts
+    @param {Tutorial} tutorials
+ */
+exports.publish = (memberData, opts, tutorials) => {
+    let classes;
+    let conf;
+    let externals;
+    let files;
+    let fromDir;
+    let globalUrl;
+    let indexUrl;
+    let interfaces;
+    let members;
+    let mixins;
+    let modules;
+    let namespaces;
+    let outputSourceFiles;
+    let packageInfo;
+    let packages;
+    const sourceFilePaths = [];
+    let sourceFiles = {};
+    let staticFileFilter;
+    let staticFilePaths;
+    let staticFiles;
+    let staticFileScanner;
+    let templatePath;
+
+    data = memberData;
+
+    conf = env.conf.templates || {};
+    conf.default = conf.default || {};
+
+    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(doclet => {
+        let sourcePath;
+
+        doclet.attribs = '';
+
+        if (doclet.examples) {
+            doclet.examples = doclet.examples.map(example => {
+                let caption;
+                let 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((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.includes(sourcePath)) {
+                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(fileName => {
+        const 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(filePath => {
+            let extraStaticFiles;
+
+            filePath = path.resolve(env.pwd, filePath);
+            extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter);
+
+            extraStaticFiles.forEach(fileName => {
+                const sourcePath = fs.toDir(filePath);
+                const 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(doclet => {
+        let docletPath;
+        const 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(doclet => {
+        const url = helper.longnameToUrl[doclet.longname];
+
+        if (url.includes('#')) {
+            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(doclet => {
+        doclet.ancestors = getAncestorLinks(doclet);
+
+        if (doclet.kind === 'member') {
+            addSignatureTypes(doclet);
+            addAttribs(doclet);
+        }
+
+        if (doclet.kind === 'constant') {
+            addSignatureTypes(doclet);
+            addAttribs(doclet);
+            doclet.kind = 'member';
+        }
+    });
+
+    members = helper.getMembers(data);
+
+    members.modules = members.modules.map(module => {
+        module.children = data({ memberof: `module:${module.name}`}).get();
+        return module;
+    })
+
+    members.tutorials = tutorials.children;
+
+    // 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.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
+    files = find({kind: 'file'});
+    packages = find({kind: 'package'});
+
+    generate('Open edX frontend-platform API Documentation',
+        packages.concat(
+            [{
+                kind: 'mainpage',
+                readme: opts.readme,
+                longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'
+            }]
+        ).concat(files), indexUrl);
+
+    Object.keys(helper.longnameToUrl).forEach(longname => {
+        const myClasses = members.classes.filter(obj => obj.longname === longname);
+        const myExternals = members.externals.filter(obj => obj.longname === longname);
+        const myInterfaces = members.interfaces.filter(obj => obj.longname === longname);
+        const myMixins = members.mixins.filter(obj => obj.longname === longname);
+        const myModules = members.modules.filter(obj => obj.longname === longname);
+        const myNamespaces = members.namespaces.filter(obj => obj.longname === longname);
+
+        const trimModuleName = (moduleName) => {
+            if (moduleName.includes('module:')) {
+                return moduleName.split(':')[1];
+            }
+            return moduleName;
+        }
+
+        if (myModules.length) {
+            generate(`${myModules[0].name}`, myModules, helper.longnameToUrl[longname], { moduleName: myModules[0].name });
+        }
+
+        if (myClasses.length) {
+            generate(`Class: ${myClasses[0].name}`, myClasses, helper.longnameToUrl[longname], { moduleName: trimModuleName(myClasses[0].memberof) });
+        }
+
+        if (myNamespaces.length) {
+            generate(`Namespace: ${myNamespaces[0].name}`, myNamespaces, helper.longnameToUrl[longname], { moduleName: trimModuleName(myNamespaces[0].memberof) });
+        }
+
+        if (myMixins.length) {
+            generate(`Mixin: ${myMixins[0].name}`, myMixins, helper.longnameToUrl[longname], { moduleName: trimModuleName(myMixins[0].memberof) });
+        }
+
+        if (myExternals.length) {
+            generate(`External: ${myExternals[0].name}`, myExternals, helper.longnameToUrl[longname], { moduleName: trimModuleName(myExternals[0].memberof) });
+        }
+
+        if (myInterfaces.length) {
+            generate(`Interface: ${myInterfaces[0].name}`, myInterfaces, helper.longnameToUrl[longname], { moduleName: trimModuleName(myInterfaces[0].memberof) });
+        }
+    });
+
+    // TODO: move the tutorial functions to templateHelper.js
+    function generateTutorial(title, tutorial, filename) {
+        const tutorialData = {
+            title: title,
+            header: tutorial.title,
+            content: tutorial.parse(),
+            children: tutorial.children
+        };
+        const tutorialPath = path.join(outdir, filename);
+        let 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({children}) {
+        children.forEach(child => {
+            generateTutorial(`Tutorial: ${child.title}`, child, helper.tutorialToUrl(child.name));
+            saveChildren(child);
+        });
+    }
+
+    saveChildren(tutorials);
+};