1 | /*==============================================================================
|
2 | Demo template, showing how documentation can be generated for `vis.js`.
|
3 |
|
4 | ------------------------------------------------------------------------------
|
5 | ## Notes on `jsdoc` code
|
6 |
|
7 | // claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness
|
8 | // doesn't try to hand them out later
|
9 | indexUrl = helper.getUniqueFilename('index');
|
10 | // don't call registerLink() on this one! 'index' is also a valid longname
|
11 |
|
12 | globalUrl = helper.getUniqueFilename('global');
|
13 | helper.registerLink('global', globalUrl);
|
14 |
|
15 | ============================================================================== */
|
16 | ;
|
17 | //var taffy = require('taffydb').taffy; // not really required here, left for reference
|
18 |
|
19 | // Internal modules of `jsdoc` are available here.
|
20 | // This is not the complete list, there may be more useful stuff in jsdoc
|
21 | // For all modules scan in: '/usr/lib/node_modules/jsdoc/lib/jsdoc/' (or similar on your system)
|
22 | var fs = require('jsdoc/fs');
|
23 | var path = require('jsdoc/path');
|
24 | var template = require('jsdoc/template');
|
25 |
|
26 |
|
27 | /**
|
28 | * Set up the template rendering engine.
|
29 | */
|
30 | function createRenderer(fromDir, data) {
|
31 | var renderer = new template.Template(fromDir); // Param is the template source directory.
|
32 | // All template files are relative to this directory!
|
33 | /**
|
34 | * Example helper method
|
35 | *
|
36 | * This can be called from within a template as follows:
|
37 | *
|
38 | * ```
|
39 | * <?js
|
40 | * var self = this;
|
41 | * ?>
|
42 | * ...
|
43 | * <?js= self.helper('hello!') ?>
|
44 | * ```
|
45 | *
|
46 | * /
|
47 | renderer.helper = function(val) {
|
48 | return 'this is a helper! ' + val;
|
49 | };
|
50 | */
|
51 |
|
52 | /**
|
53 | * Retrieves jsdoc info for the passed instance method.
|
54 | */
|
55 | renderer.getComment = function(methodName) {
|
56 | var tmp = data().filter({longname: methodName}).get()[0];
|
57 |
|
58 | if (tmp === undefined) {
|
59 | throw new Error('Could not find jsdoc for: ' + methodName);
|
60 | }
|
61 |
|
62 | // NOTE: Following does not show up with `gulp docs`, need to do call directly
|
63 | // console.log(JSON.stringify(tmp, null, 2));
|
64 |
|
65 | // Some restructuring, to adapt it to the docs layout
|
66 | // This needs some work to make it handle 0 and > 1 parameters
|
67 | var paramText = "";
|
68 | if (tmp.params !== undefined && tmp.params.length > 0) {
|
69 | let param = tmp.params[0];
|
70 | let tmpText = param.type.names.join('|') + ' ' + param.name;
|
71 | if (param.optional === true) {
|
72 | tmpText = '[' + tmpText + ']';
|
73 | }
|
74 | paramText = '<code>' + tmpText + '</code>';
|
75 | }
|
76 | var prototype = tmp.name + '(' + paramText + ')';
|
77 |
|
78 | var returns = 'none';
|
79 | if (tmp.returns !== undefined && tmp.returns.length > 0) {
|
80 | let name = tmp.returns[0].type.names[0];
|
81 | if (name !== "undefined") {
|
82 | returns = name;
|
83 | }
|
84 | }
|
85 |
|
86 | return {
|
87 | name: tmp.name,
|
88 | prototype: prototype,
|
89 | returns: returns,
|
90 | description: tmp.description
|
91 | }
|
92 | };
|
93 |
|
94 | return renderer;
|
95 | }
|
96 |
|
97 |
|
98 | /**
|
99 | Entry point for the template.
|
100 |
|
101 | This is called from `jsdoc` during execution
|
102 |
|
103 | @param {TAFFY} taffyData See <http://taffydb.com/>.
|
104 | @param {object} opts
|
105 | @param {Tutorial} tutorials
|
106 | */
|
107 | exports.publish = function(taffyData, opts, tutorials) {
|
108 | //console.log(JSON.stringify(opts, null, 2));
|
109 |
|
110 | var fromDir = path.resolve(opts.template);
|
111 | var toDir = path.join(opts.destination);
|
112 | var renderer = createRenderer(fromDir, taffyData);
|
113 |
|
114 | var docFiles = fs.ls(fromDir, 3);
|
115 | docFiles.forEach(function(fileName) {
|
116 | // Template filenames need to be relative to template source dir
|
117 | var relName = path.relative(fromDir, fileName);
|
118 | var outFile = path.join(toDir, relName);
|
119 |
|
120 | if (/publish.js$/.test(fileName)) return; // Skip self
|
121 | if (/README.md$/.test(fileName)) return; // Skip own README
|
122 | if (/\.tmpl$/.test(fileName)) return; // Skip .tmpl files; these are used as partials only
|
123 |
|
124 | if (!/\.html$/.test(fileName)) {
|
125 | // Just plain copy over non-html files
|
126 | var tmpDir = fs.toDir(outFile);
|
127 | fs.mkPath(tmpDir);
|
128 | fs.copyFileSync(fileName, tmpDir);
|
129 | return;
|
130 | }
|
131 |
|
132 | // Render html files as templates
|
133 | //console.log(relName);
|
134 | var html = renderer.partial(relName, {});
|
135 | fs.mkPath(fs.toDir(outFile));
|
136 | fs.writeFileSync(outFile, html, 'utf8');
|
137 | });
|
138 |
|
139 | //console.log(JSON.stringify(env, null, 2));
|
140 | };
|