1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
var async = require('../../dist/async');
var fs = require('fs-extra');
var path = require('path');
var $ = require('cheerio');
var _ = require('lodash');
var docsDir = path.join(__dirname, '../../docs');
var pageTitle = 'Methods:';
var docFilename = 'docs.html';
var mainModuleFile = 'module-async.html';
var mainSectionId = '#main';
var mainScrollableSection = '#main-container';
var sectionTitleClass = '.page-title';
var HTMLFileBegin = '<!DOCTYPE html>\n<html lang="en">\n<head>\n';
var HTMLFileHeadBodyJoin = '</head>\n<body>';
var HTMLFileEnd = '</body>';
var additionalFooterText = ' Documentation has been modified from the original. ' +
' For more information, please see the <a href="https://github.com/caolan/async">async</a> repository.';
function generateHTMLFile(filename, $page, callback) {
var methodName = filename.match(/\/(\w+)\.js\.html$/);
if (methodName) {
var $thisMethodDocLink = $page.find('#toc').find('a[href="'+docFilename+'#'+methodName[1]+'"]');
$thisMethodDocLink.parent().addClass('active');
}
// generate an HTML file from a cheerio object
var HTMLdata = HTMLFileBegin + $page.find('head').html()
+ HTMLFileHeadBodyJoin + $page.find('body').html()
+ HTMLFileEnd;
fs.writeFile(filename, HTMLdata, callback);
}
function extractModuleFiles(files) {
return _.filter(files, function(file) {
return _.startsWith(file, 'module') && file !== mainModuleFile;
});
}
function getSearchableInfo($page, callback) {
var $sourceLinks = $page.find('a[href$=".js.html"]');
var sourceFiles = $sourceLinks.map(function() {
return $(this).attr('href');
}).toArray().sort();
var $methodLinks = $page.find('nav').find('a');
var methods = $methodLinks.map(function() {
var methodName = $(this).text();
return (methodName === 'Home' ? null : methodName);
}).toArray().sort();
fs.mkdirsSync(path.join(docsDir, 'data'));
async.parallel([
function(fileCallback) {
fs.writeJson(path.join(docsDir, 'data/sourceFiles.json'), sourceFiles, fileCallback);
},
function(fileCallback) {
fs.writeJson(path.join(docsDir, 'data/methodNames.json'), methods, fileCallback);
}
], callback);
}
function combineFakeModules(files, callback) {
var moduleFiles = extractModuleFiles(files);
fs.readFile(path.join(docsDir, mainModuleFile), 'utf8', function(err, mainModuleData) {
if (err) return callback(err);
var $mainPage = $(mainModuleData);
// each 'module' (category) has a separate page, with all of the
// important information in a 'main' div. Combine all of these divs into
// one on the actual module page (async)
async.eachSeries(moduleFiles, function(file, fileCallback) {
fs.readFile(path.join(docsDir, file), 'utf8', function(err, moduleData) {
if (err) return fileCallback(err);
var $modulePage = $(moduleData);
var moduleName = $modulePage.find(sectionTitleClass).text();
$modulePage.find(sectionTitleClass).attr('id', moduleName.toLowerCase());
$mainPage.find(mainScrollableSection).append($modulePage.find(mainScrollableSection).html());
return fileCallback();
});
}, function(err) {
if (err) return callback(err);
getSearchableInfo($mainPage, function(err) {
if (err) return callback(err);
generateHTMLFile(path.join(docsDir, docFilename), $mainPage, callback);
});
});
});
}
function applyPreCheerioFixes(data) {
var rIncorrectCFText = />ControlFlow</g;
var fixedCFText = '>Control Flow<';
var rIncorrectModuleText = />module:(\w+)\.(\w+)</g;
// the heading needs additional padding at the top so it doesn't get cutoff
return data
// for JSDoc to work, the module needs to be labelled 'ControlFlow', while
// on the page it should appear as 'Control Flow'
.replace(rIncorrectCFText, fixedCFText)
// for return types, JSDoc doesn't allow replacing the link text, so it
// needs to be done here
.replace(rIncorrectModuleText, function(match, moduleName, methodName) {
return '>'+methodName+'<';
});
}
function scrollSpyFix($page, $nav) {
// move everything into one big ul (for Bootstrap scroll-spy)
var $ul = $nav.children('ul');
$ul.addClass('nav').addClass('methods');
$ul.find('.methods').each(function() {
var $methodsList = $(this);
var $methods = $methodsList.find('[data-type="method"]');
var $parentLi = $methodsList.parent();
$methodsList.remove();
$methods.remove();
$parentLi.after($methods);
$parentLi.addClass('toc-header');
});
$page.find('[data-type="method"]').addClass("toc-method");
$page.find('[id^="."]').each(function() {
var $ele = $(this);
var id = $(this).attr('id');
$ele.attr('id', id.replace('.', ''));
});
}
function fixToc(file, $page, moduleFiles) {
// remove `async` listing from toc
$page.find('a[href="'+mainModuleFile+'"]').parent().remove();
// change toc title
var $nav = $page.find('nav');
$nav.attr('id', 'toc');
$nav.children('h3').text(pageTitle);
$nav.children('h2').remove();
scrollSpyFix($page, $nav);
var prependFilename = (file === docFilename) ? '' : docFilename;
// make everything point to the same 'docs.html' page
_.each(moduleFiles, function(filename) {
$page.find('[href^="'+filename+'"]').each(function() {
var $ele = $(this);
var href = $ele.attr('href');
// category titles should sections title, while everything else
// points to the correct listing
if (href === filename) {
var moduleName = $ele.text().toLowerCase().replace(/\s/g, '').replace('.', '');
$ele.attr('href', prependFilename+'#'+moduleName);
} else {
$ele.attr('href', href.replace(filename, prependFilename).replace('#.', '#'));
}
});
});
}
function fixFooter($page) {
// add a note to the footer that the documentation has been modified
var $footer = $page.find('footer');
$footer.append(additionalFooterText);
$page.find(mainScrollableSection).append($footer);
}
function fixModuleLinks(files, callback) {
var moduleFiles = extractModuleFiles(files);
async.each(files, function(file, fileCallback) {
var filePath = path.join(docsDir, file);
fs.readFile(filePath, 'utf8', function(err, fileData) {
if (err) return fileCallback(err);
var $file = $(applyPreCheerioFixes(fileData));
fixToc(file, $file, moduleFiles);
fixFooter($file);
$file.find('[href="'+mainModuleFile+'"]').attr('href', docFilename);
generateHTMLFile(filePath, $file, fileCallback);
});
}, callback);
}
fs.copySync(path.join(__dirname, '../../dist/async.js'), path.join(docsDir, 'scripts/async.js'), { clobber: true });
fs.copySync(path.join(__dirname, './jsdoc-custom.js'), path.join(docsDir, 'scripts/jsdoc-custom.js'), { clobber: true });
fs.copySync(path.join(__dirname, '..', '..', 'logo', 'favicon.ico'), path.join(docsDir, 'favicon.ico'), { clobber: true });
fs.copySync(path.join(__dirname, '..', '..', 'logo', 'async-logo.svg'), path.join(docsDir, 'img', 'async-logo.svg'), { clobber: true });
fs.readdir(docsDir, function(err, files) {
if (err) {
throw err;
}
var HTMLFiles = _.filter(files, function(file) {
return path.extname(file) === '.html';
});
async.waterfall([
function(callback) {
combineFakeModules(HTMLFiles, function(err) {
if (err) return callback(err);
HTMLFiles.push(docFilename);
return callback(null);
});
},
function(callback) {
fixModuleLinks(HTMLFiles, callback);
}
], function(err) {
if (err) throw err;
console.log('Docs generated successfully');
});
});
|
