/tags/jsdoc_toolkit-2.3.2/jsdoc-toolkit/templates/jsdoc/publish.js

http://jsdoc-toolkit.googlecode.com/ · JavaScript · 200 lines · 141 code · 37 blank · 22 comment · 29 complexity · 77d2538463bbc88e7fe1f7ef9fe8cc9b MD5 · raw file

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