update the default template to generate pretty-printed source files (j…

…sdoc#208)

enabled by default. to disable pretty-printed source files, add the
property templates.default.outputSourceFiles: false to your conf.json
file.

LICENSE.md

@@ -115,6 +115,17 @@ The source code for github-flavored-markdown is available at:
 https://github.com/hegemonic/github-flavored-markdown
 
 
+## Google Code Prettify ##
+
+Google Code Prettify is distributed under the Apache License 2.0, which is
+included with this package.
+
+Copyright (c) 2006 Google Inc.
+
+The source code for Google Code Prettify is available at:
+https://code.google.com/p/google-code-prettify/
+
+
 ## Jasmine ##
 
 Jasmine is distributed under the MIT license, which is reproduced above.
@@ -139,7 +150,7 @@ https://github.com/mhevery/jasmine-node
 
 js2xmlparser is distributed under the MIT license, which is reproduced above.
 
-Copyright (C) 2012 Michael Kourlas.
+Copyright (c) 2012 Michael Kourlas.
 
 The source code for js2xmlparser is available at:
 https://github.com/michaelkourlas/node-js2xmlparser
@@ -249,6 +260,18 @@ The source code for TaffyDB is available at:
 https://github.com/hegemonic/taffydb
 
 
+## Tomorrow Theme for Google Code Prettify ##
+
+License information for the Tomorrow Theme for Google Code Prettify is not
+available. It is assumed that the package is distributed under an open source
+license that is compatible with the Apache License 2.0.
+
+Copyright (c) Yoshihide Jimbo.
+
+The source code for the Tomorrow Theme is available at:
+https://github.com/jmblog/color-themes-for-google-code-prettify
+
+
 ## Rhino ##
 
 Rhino is distributed under the following licenses:

conf.json.EXAMPLE

@@ -9,7 +9,10 @@
     "plugins": [],
     "templates": {
         "cleverLinks": false,
-        "monospaceLinks": false
+        "monospaceLinks": false,
+        "default": {
+            "outputSourceFiles": true
+        }
     },
     "jsVersion": 180
 }

lib/jsdoc/path.js

@@ -0,0 +1,65 @@
+/**
+ * Extended version of the standard `path` module.
+ * @module jsdoc/path
+ */
+
+var path = require('path');
+
+
+function prefixReducer(previousPath, current) {
+    var currentPath = [];
+
+    // if previousPath is defined, but has zero length, there's no common prefix; move along
+    if (previousPath && !previousPath.length) {
+        return currentPath;
+    }
+
+    currentPath = path.resolve( process.cwd(), path.dirname(current) ).split(path.sep);
+
+    if (previousPath) {
+        // remove chunks that exceed the previous path's length
+        currentPath = currentPath.slice(0, previousPath.length);
+
+        // if a chunk doesn't match the previous path, remove everything from that chunk on
+        for (var i = 0, l = currentPath.length; i < l; i++) {
+            if (currentPath[i] !== previousPath[i]) {
+                currentPath.splice(i, currentPath.length - i);
+                break;
+            }
+        }
+    }
+
+    return currentPath;
+}
+
+/**
+ * Find the common prefix for an array of paths. If there is a common prefix, a trailing separator
+ * is appended to the prefix. Relative paths are resolved relative to the current working directory.
+ *
+ * For example, assuming that the current working directory is `/Users/jsdoc`:
+ *
+ * + For paths `foo/bar/baz/qux.js`, `foo/bar/baz/quux.js`, and `foo/bar/baz.js`, the common prefix
+ * is `/Users/jsdoc/foo/bar/`.
+ * + For paths `../jsdoc/foo/bar/baz/qux/quux/test.js`, `/Users/jsdoc/foo/bar/bazzy.js`, and
+ * `../../Users/jsdoc/foo/bar/foobar.js`, the common prefix is `/Users/jsdoc/foo/bar/`.
+ * + For paths `foo/bar/baz/qux.js` and `../../Library/foo/bar/baz.js`, there is no common prefix,
+ * and an empty string is returned.
+ *
+ * @param {Array.<string>} paths - The paths to search for a common prefix.
+ * @return {string} The common prefix, or an empty string if there is no common prefix.
+ */
+exports.commonPrefix = function(paths) {
+    var common = paths.reduce(prefixReducer, undefined);
+
+    // if there's anything left (other than a placeholder for a leading slash), add a placeholder
+    // for a trailing slash
+    if ( common.length && (common.length > 1 || common[0] !== '') ) {
+        common.push('');
+    }
+
+    return common.join(path.sep);
+};
+
+Object.keys(path).forEach(function(member) {
+    exports[member] = path[member];
+});

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "jsdoc",
 	"version": "3.1.0-dev",
-	"revision": "1358265302670",
+	"revision": "1358915320017",
 	"description": "An API documentation generator for JavaScript.",
 	"keywords": [ "documentation", "javascript" ],
 	"licenses": [

templates/default/publish.js

@@ -1,8 +1,9 @@
 /*global env: true */
 var template = require('jsdoc/template'),
     fs = require('jsdoc/fs'),
-    path = require('path'),
+    path = require('jsdoc/path'),
     taffy = require('taffydb').taffy,
+    handle = require('jsdoc/util/error').handle,
     helper = require('jsdoc/util/templateHelper'),
     htmlsafe = helper.htmlsafe,
     linkto = helper.linkto,
@@ -57,8 +58,38 @@ function addAttribs(f) {
 
     f.attribs = '<span class="type-signature">'+htmlsafe(attribs.length? '<'+attribs.join(', ')+'> ' : '')+'</span>';
 }
+
+function shortenPaths(files, commonPrefix) {
+    // always use forward slashes
+    var regexp = new RegExp('\\\\', 'g');
+
+    Object.keys(files).forEach(function(file) {
+        files[file].shortened = files[file].resolved.replace(commonPrefix, '')
+            .replace(regexp, '/');
+    });
+
+    return files;
+}
+
+function resolveSourcePath(filepath) {
+    return path.resolve(process.cwd(), filepath);
+}
+
+function getPathFromDoclet(doclet) {
+    if (!doclet.meta) {
+        return;
+    }
+
+    var filepath = doclet.meta.path && doclet.meta.path !== 'null' ?
+        doclet.meta.path + '/' + doclet.meta.filename :
+        doclet.meta.filename;
+
+    return filepath;
+}
 
-function generate(title, docs, filename) {
+function generate(title, docs, filename, resolveLinks) {
+    resolveLinks = resolveLinks === false ? false : true;
+
     var docData = {
         title: title,
         docs: docs
@@ -67,11 +98,35 @@ function generate(title, docs, filename) {
     var outpath = path.join(outdir, filename),
         html = view.render('container.tmpl', docData);
 
-    html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
+    if (resolveLinks) {
+        html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
+    }
 
     fs.writeFileSync(outpath, html, 'utf8');
 }
 
+function generateSourceFiles(sourceFiles) {
+    Object.keys(sourceFiles).forEach(function(file) {
+        var source;
+        // links are keyed to the shortened path in each doclet's `meta.filename` 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, 'utf8') )
+            };
+        }
+        catch(e) {
+            handle(e);
+        }
+
+        generate('Source: ' + sourceFiles[file].shortened, [source], sourceOutfile,
+            false);
+    });
+}
+
 /**
  * Create the navigation sidebar.
  * @param {object} members The members that will be used to create the sidebar.
@@ -204,6 +259,9 @@ function buildNav(members) {
 exports.publish = function(taffyData, opts, tutorials) {
     data = taffyData;
 
+    var conf = env.conf.templates || {};
+    conf['default'] = conf['default'] || {};
+
     var templatePath = opts.template;
     view = new template.Template(templatePath + '/tmpl');
 
@@ -224,6 +282,8 @@ exports.publish = function(taffyData, opts, tutorials) {
     data = helper.prune(data);
     data.sort('longname, version, since');
 
+    var sourceFiles = {};
+    var sourceFilePaths = [];
     data().each(function(doclet) {
          doclet.attribs = '';
 
@@ -247,6 +307,19 @@ exports.publish = function(taffyData, opts, tutorials) {
                 doclet.see[i] = hashToLink(doclet, seeItem);
             });
         }
+
+        // build a list of source files
+        var sourcePath;
+        var resolvedSourcePath;
+        if (doclet.meta) {
+            sourcePath = getPathFromDoclet(doclet);
+            resolvedSourcePath = resolveSourcePath(sourcePath);
+            sourceFiles[sourcePath] = {
+                resolved: resolvedSourcePath,
+                shortened: null
+            };
+            sourceFilePaths.push(resolvedSourcePath);
+        }
     });
 
     // update outdir if necessary, then create outdir
@@ -266,9 +339,20 @@ exports.publish = function(taffyData, opts, tutorials) {
         fs.copyFileSync(fileName, toDir);
     });
 
+    sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) );
     data().each(function(doclet) {
         var url = helper.createLink(doclet);
         helper.registerLink(doclet.longname, url);
+
+        // replace the filename with a shortened version of the full path
+        var docletPath;
+        if (doclet.meta) {
+            docletPath = getPathFromDoclet(doclet);
+            docletPath = sourceFiles[docletPath].shortened;
+            if (docletPath) {
+                doclet.meta.filename = docletPath;
+            }
+        }
     });
 
     data().each(function(doclet) {
@@ -316,6 +400,12 @@ exports.publish = function(taffyData, opts, tutorials) {
     // once for all
     view.nav = buildNav(members);
 
+    // only output pretty-printed source files if requested; do this before generating any other
+    // pages, so the other pages can link to the source files
+    if (conf['default'].outputSourceFiles) {
+        generateSourceFiles(sourceFiles);
+    }
+
     if (members.globals.length) { generate('Global', [{kind: 'globalobj'}], globalUrl); }
 
     // index page displays information from package.json and lists files

templates/default/static/styles/jsdoc-default.css

@@ -220,6 +220,11 @@ h6
 {
 	border: 1px solid #ddd;
 	width: 80%;
+    overflow: auto;
+}
+
+.prettyprint.source {
+    width: inherit;
 }
 
 .prettyprint code