| 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 "<"+srcFilePath+">"; |
| 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 |
} |