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

  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}