/tags/jsdoc_toolkit-2.3.2/jsdoc-toolkit/templates/jsdoc/publish.js
JavaScript | 200 lines | 141 code | 37 blank | 22 comment | 29 complexity | 77d2538463bbc88e7fe1f7ef9fe8cc9b MD5 | raw file
1/** Called automatically by JsDoc Toolkit. */
2function 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 var output = "";
81 output = classTemplate.process(symbol);
82
83 IO.saveFile(publish.conf.outDir+"symbols/", ((JSDOC.opt.u)? Link.filemap[symbol.alias] : symbol.alias) + publish.conf.ext, output);
84 }
85
86 // regenerate the index with different relative links, used in the index pages
87 Link.base = "";
88 publish.classesIndex = classesTemplate.process(classes);
89
90 // create the class index page
91 try {
92 var classesindexTemplate = new JSDOC.JsPlate(publish.conf.templatesDir+"index.tmpl");
93 }
94 catch(e) { print(e.message); quit(); }
95
96 var classesIndex = classesindexTemplate.process(classes);
97 IO.saveFile(publish.conf.outDir, "index"+publish.conf.ext, classesIndex);
98 classesindexTemplate = classesIndex = classes = null;
99
100 // create the file index page
101 try {
102 var fileindexTemplate = new JSDOC.JsPlate(publish.conf.templatesDir+"allfiles.tmpl");
103 }
104 catch(e) { print(e.message); quit(); }
105
106 var documentedFiles = symbols.filter(isaFile); // files that have file-level docs
107 var allFiles = []; // not all files have file-level docs, but we need to list every one
108
109 for (var i = 0; i < files.length; i++) {
110 allFiles.push(new JSDOC.Symbol(files[i], [], "FILE", new JSDOC.DocComment("/** */")));
111 }
112
113 for (var i = 0; i < documentedFiles.length; i++) {
114 var offset = files.indexOf(documentedFiles[i].alias);
115 allFiles[offset] = documentedFiles[i];
116 }
117
118 allFiles = allFiles.sort(makeSortby("name"));
119
120 // output the file index page
121 var filesIndex = fileindexTemplate.process(allFiles);
122 IO.saveFile(publish.conf.outDir, "files"+publish.conf.ext, filesIndex);
123 fileindexTemplate = filesIndex = files = null;
124}
125
126
127/** Just the first sentence (up to a full stop). Should not break on dotted variable names. */
128function summarize(desc) {
129 if (typeof desc != "undefined")
130 return desc.match(/([\w\W]+?\.)[^a-z0-9_$]/i)? RegExp.$1 : desc;
131}
132
133/** Make a symbol sorter by some attribute. */
134function makeSortby(attribute) {
135 return function(a, b) {
136 if (a[attribute] != undefined && b[attribute] != undefined) {
137 a = a[attribute].toLowerCase();
138 b = b[attribute].toLowerCase();
139 if (a < b) return -1;
140 if (a > b) return 1;
141 return 0;
142 }
143 }
144}
145
146/** Pull in the contents of an external file at the given path. */
147function include(path) {
148 var path = publish.conf.templatesDir+path;
149 return IO.readFile(path);
150}
151
152/** Turn a raw source file into a code-hilited page in the docs. */
153function makeSrcFile(path, srcDir, name) {
154 if (JSDOC.opt.s) return;
155
156 if (!name) {
157 name = path.replace(/\.\.?[\\\/]/g, "").replace(/[\\\/]/g, "_");
158 name = name.replace(/\:/g, "_");
159 }
160
161 var src = {path: path, name:name, charset: IO.encoding, hilited: ""};
162
163 if (defined(JSDOC.PluginManager)) {
164 JSDOC.PluginManager.run("onPublishSrc", src);
165 }
166
167 if (src.hilited) {
168 IO.saveFile(srcDir, name+publish.conf.ext, src.hilited);
169 }
170}
171
172/** Build output for displaying function parameters. */
173function makeSignature(params) {
174 if (!params) return "()";
175 var signature = "("
176 +
177 params.filter(
178 function($) {
179 return $.name.indexOf(".") == -1; // don't show config params in signature
180 }
181 ).map(
182 function($) {
183 return $.name;
184 }
185 ).join(", ")
186 +
187 ")";
188 return signature;
189}
190
191/** Find symbol {@link ...} strings in text and turn into html links */
192function resolveLinks(str, from) {
193 str = str.replace(/\{@link ([^} ]+) ?\}/gi,
194 function(match, symbolName) {
195 return new Link().toSymbol(symbolName);
196 }
197 );
198
199 return str;
200}