jsdoc-toolkit/templates/jsdoc/publish.js

   1 /** Called automatically by JsDoc Toolkit. */
   2 function publish(symbolSet) {
   3         publish.conf = {  // trailing slash expected for dirs
   4                 ext:         ".html",
   5                 outDir:      JSDOC.opt.d || SYS.pwd+"../out/jsdoc/",
   6                 templatesDir: JSDOC.opt.t || SYS.pwd+"../templates/jsdoc/",
   7                 symbolsDir:  "symbols/",
   8                 srcDir:      "symbols/src/"
   9         };
  10
  11         // is source output is suppressed, just display the links to the source file
  12         if (JSDOC.opt.s && defined(Link) && Link.prototype._makeSrcLink) {
  13                 Link.prototype._makeSrcLink = function(srcFilePath) {
  14                         return "&lt;"+srcFilePath+"&gt;";
  15                 }
  16         }
  17
  18         // create the folders and subfolders to hold the output
  19         IO.mkPath((publish.conf.outDir+"symbols/src").split("/"));
  20
  21         // used to allow Link to check the details of things being linked to
  22         Link.symbolSet = symbolSet;
  23
  24         // create the required templates
  25         try {
  26                 var classTemplate = new JSDOC.JsPlate(publish.conf.templatesDir+"class.tmpl");
  27                 var classesTemplate = new JSDOC.JsPlate(publish.conf.templatesDir+"allclasses.tmpl");
  28         }
  29         catch(e) {
  30                 print("Couldn't create the required templates: "+e);
  31                 quit();
  32         }
  33
  34         // some ustility filters
  35         function hasNoParent($) {return ($.memberOf == "")}
  36         function isaFile($) {return ($.is("FILE"))}
  37         function isaClass($) {return ($.is("CONSTRUCTOR") || $.isNamespace)}
  38
  39         // get an array version of the symbolset, useful for filtering
  40         var symbols = symbolSet.toArray();
  41
  42         // create the hilited source code files
  43         var files = JSDOC.opt.srcFiles;
  44         for (var i = 0, l = files.length; i < l; i++) {
  45                 var file = files[i];
  46                 var srcDir = publish.conf.outDir + "symbols/src/";
  47                 makeSrcFile(file, srcDir);
  48         }
  49
  50         // get a list of all the classes in the symbolset
  51         var classes = symbols.filter(isaClass).sort(makeSortby("alias"));
  52
  53         // create a filemap in which outfiles must be to be named uniquely, ignoring case
  54         if (JSDOC.opt.u) {
  55                 var filemapCounts = {};
  56                 Link.filemap = {};
  57                 for (var i = 0, l = classes.length; i < l; i++) {
  58                         var lcAlias = classes[i].alias.toLowerCase();
  59
  60                         if (!filemapCounts[lcAlias]) filemapCounts[lcAlias] = 1;
  61                         else filemapCounts[lcAlias]++;
  62
  63                         Link.filemap[classes[i].alias] =
  64                                 (filemapCounts[lcAlias] > 1)?
  65                                 lcAlias+"_"+filemapCounts[lcAlias] : lcAlias;
  66                 }
  67         }
  68
  69         // create a class index, displayed in the left-hand column of every class page
  70         Link.base = "../";
  71         publish.classesIndex = classesTemplate.process(classes); // kept in memory
  72
  73         // create each of the class pages
  74         for (var i = 0, l = classes.length; i < l; i++) {
  75                 var symbol = classes[i];
  76
  77                 symbol.events = symbol.getEvents();   // 1 order matters
  78                 symbol.methods = symbol.getMethods(); // 2
  79
  80                 Link.currentSymbol= symbol;
  81                 var output = "";
  82                 output = classTemplate.process(symbol);
  83
  84                 IO.saveFile(publish.conf.outDir+"symbols/", ((JSDOC.opt.u)? Link.filemap[symbol.alias] : symbol.alias) + publish.conf.ext, output);
  85         }
  86
  87         // regenerate the index with different relative links, used in the index pages
  88         Link.base = "";
  89         publish.classesIndex = classesTemplate.process(classes);
  90
  91         // create the class index page
  92         try {
  93                 var classesindexTemplate = new JSDOC.JsPlate(publish.conf.templatesDir+"index.tmpl");
  94         }
  95         catch(e) { print(e.message); quit(); }
  96
  97         var classesIndex = classesindexTemplate.process(classes);
  98         IO.saveFile(publish.conf.outDir, "index"+publish.conf.ext, classesIndex);
  99         classesindexTemplate = classesIndex = classes = null;
 100
 101         // create the file index page
 102         try {
 103                 var fileindexTemplate = new JSDOC.JsPlate(publish.conf.templatesDir+"allfiles.tmpl");
 104         }
 105         catch(e) { print(e.message); quit(); }
 106
 107         var documentedFiles = symbols.filter(isaFile); // files that have file-level docs
 108         var allFiles = []; // not all files have file-level docs, but we need to list every one
 109
 110         for (var i = 0; i < files.length; i++) {
 111                 allFiles.push(new JSDOC.Symbol(files[i], [], "FILE", new JSDOC.DocComment("/** */")));
 112         }
 113
 114         for (var i = 0; i < documentedFiles.length; i++) {
 115                 var offset = files.indexOf(documentedFiles[i].alias);
 116                 allFiles[offset] = documentedFiles[i];
 117         }
 118
 119         allFiles = allFiles.sort(makeSortby("name"));
 120
 121         // output the file index page
 122         var filesIndex = fileindexTemplate.process(allFiles);
 123         IO.saveFile(publish.conf.outDir, "files"+publish.conf.ext, filesIndex);
 124         fileindexTemplate = filesIndex = files = null;
 125 }
 126
 127
 128 /** Just the first sentence (up to a full stop). Should not break on dotted variable names. */
 129 function summarize(desc) {
 130         if (typeof desc != "undefined")
 131                 return desc.match(/([\w\W]+?\.)[^a-z0-9_$]/i)? RegExp.$1 : desc;
 132 }
 133
 134 /** Make a symbol sorter by some attribute. */
 135 function makeSortby(attribute) {
 136         return function(a, b) {
 137                 if (a[attribute] != undefined && b[attribute] != undefined) {
 138                         a = a[attribute].toLowerCase();
 139                         b = b[attribute].toLowerCase();
 140                         if (a < b) return -1;
 141                         if (a > b) return 1;
 142                         return 0;
 143                 }
 144         }
 145 }
 146
 147 /** Pull in the contents of an external file at the given path. */
 148 function include(path) {
 149         var path = publish.conf.templatesDir+path;
 150         return IO.readFile(path);
 151 }
 152
 153 /** Turn a raw source file into a code-hilited page in the docs. */
 154 function makeSrcFile(path, srcDir, name) {
 155         if (JSDOC.opt.s) return;
 156
 157         if (!name) {
 158                 name = path.replace(/\.\.?[\\\/]/g, "").replace(/[\\\/]/g, "_");
 159                 name = name.replace(/\:/g, "_");
 160         }
 161
 162         var src = {path: path, name:name, charset: IO.encoding, hilited: ""};
 163
 164         if (defined(JSDOC.PluginManager)) {
 165                 JSDOC.PluginManager.run("onPublishSrc", src);
 166         }
 167
 168         if (src.hilited) {
 169                 IO.saveFile(srcDir, name+publish.conf.ext, src.hilited);
 170         }
 171 }
 172
 173 /** Build output for displaying function parameters. */
 174 function makeSignature(params) {
 175         if (!params) return "()";
 176         var signature = "("
 177         +
 178         params.filter(
 179                 function($) {
 180                         return $.name.indexOf(".") == -1; // don't show config params in signature
 181                 }
 182         ).map(
 183                 function($) {
 184                         return $.name;
 185                 }
 186         ).join(", ")
 187         +
 188         ")";
 189         return signature;
 190 }
 191
 192 /** Find symbol {@link ...} strings in text and turn into html links */
 193 function resolveLinks(str, from) {
 194         str = str.replace(/\{@link ([^} ]+) ?\}/gi,
 195                 function(match, symbolName) {
 196                         return new Link().toSymbol(symbolName);
 197                 }
 198         );
 199
 200         return str;
 201 }