|
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 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. */ |
|
128 function 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. */ |
|
134 function 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. */ |
|
147 function 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. */ |
|
153 function 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. */ |
|
173 function 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 */ |
|
192 function 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 } |