Home | History | Annotate | Download | only in jsdoc-template 
      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+"../jsdoc-template/",
      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 }
    202