Skip to content

Commit d6706ef

Browse files
IgorMinarIgorMinar
committed
chore(docs): use symlinks to build docs
so that we can just edit source files without rebuilding docs. this works for all docs files, except for those that are generated or rewritten during build.
1 parent b08d4b2 commit d6706ef

File tree

3 files changed

+53
-46
lines changed

3 files changed

+53
-46
lines changed

‎docs/src/gen-docs.js

Lines changed: 20 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,10 @@ process.on('uncaughtException', function(err) {
1212
var start = now();
1313
var docs;
1414

15-
writer.makeDir('build/docs/syntaxhighlighter').then(function() {
16-
console.log('Generating Angular Reference Documentation...');
15+
writer.makeDir('build/docs/', true).then(function() {
16+
return writer.makeDir('build/docs/partials/');
17+
}).then(function() {
18+
console.log('Generating AngularJS Reference Documentation...');
1719
return reader.collect();
1820
}).then(function generateHtmlDocPartials(docs_) {
1921
docs = docs_;
@@ -41,8 +43,10 @@ writer.makeDir('build/docs/syntaxhighlighter').then(function() {
4143
function writeTheRest(writesFuture) {
4244
var metadata = ngdoc.metadata(docs);
4345

44-
writesFuture.push(writer.copyDir('img'));
45-
writesFuture.push(writer.copyDir('font'));
46+
writesFuture.push(writer.symlinkTemplate('css'));
47+
writesFuture.push(writer.symlinkTemplate('font'));
48+
writesFuture.push(writer.symlinkTemplate('img'));
49+
writesFuture.push(writer.symlinkTemplate('js'));
4650

4751
var manifest = 'manifest="/build/docs/appcache.manifest"';
4852

@@ -66,38 +70,27 @@ function writeTheRest(writesFuture) {
6670
writesFuture.push(writer.copy('docs/src/templates/index.html', 'index-jq-debug.html',
6771
writer.replace, {'doc:manifest': ''}));
6872

69-
writesFuture.push(writer.copyTpl('offline.html'));
70-
writesFuture.push(writer.copyTpl('docs-scenario.html'));
71-
writesFuture.push(writer.copyTpl('js/jquery.min.js'));
72-
writesFuture.push(writer.copyTpl('js/jquery.js'));
73+
writesFuture.push(writer.symlinkTemplate('offline.html'));
7374

74-
writesFuture.push(writer.output('js/docs-keywords.js',
75+
writesFuture.push(writer.copyTemplate('docs-scenario.html')); // will be rewritten, don't symlink
76+
writesFuture.push(writer.output('docs-scenario.js', ngdoc.scenarios(docs)));
77+
78+
writesFuture.push(writer.output('docs-keywords.js',
7579
['NG_PAGES=', JSON.stringify(metadata).replace(/{/g, '\n{'), ';']));
7680
writesFuture.push(writer.output('sitemap.xml', new SiteMap(docs).render()));
77-
writesFuture.push(writer.output('docs-scenario.js', ngdoc.scenarios(docs)));
81+
7882
writesFuture.push(writer.output('robots.txt', 'Sitemap: http://docs.angularjs.org/sitemap.xml\n'));
7983
writesFuture.push(writer.output('appcache.manifest',appCache()));
80-
writesFuture.push(writer.copyTpl('.htaccess'));
84+
writesFuture.push(writer.copyTemplate('.htaccess')); // will be rewritten, don't symlink
8185

82-
writesFuture.push(writer.copy('docs/src/templates/js/docs.js', 'js/docs.js'));
83-
84-
writesFuture.push(writer.copy('docs/src/templates/css/bootstrap.min.css', 'css/bootstrap.min.css'));
85-
writesFuture.push(writer.copy('docs/src/templates/css/docs.css', 'css/docs.css'));
86-
writesFuture.push(writer.copy('docs/src/templates/css/font-awesome.css', 'css/font-awesome.css'));
87-
88-
writesFuture.push(writer.copyTpl('font/fontawesome-webfont.eot'));
89-
writesFuture.push(writer.copyTpl('font/fontawesome-webfont.svg'));
90-
writesFuture.push(writer.copyTpl('font/fontawesome-webfont.svgz'));
91-
writesFuture.push(writer.copyTpl('font/fontawesome-webfont.ttf'));
92-
writesFuture.push(writer.copyTpl('font/fontawesome-webfont.woff'));
93-
94-
writesFuture.push(writer.copyTpl('app.yaml'));
95-
writesFuture.push(writer.copyTpl('index.yaml'));
96-
writesFuture.push(writer.copyTpl('favicon.ico'));
97-
writesFuture.push(writer.copyTpl('main.py'));
86+
writesFuture.push(writer.symlinkTemplate('app.yaml'));
87+
writesFuture.push(writer.symlinkTemplate('index.yaml'));
88+
writesFuture.push(writer.symlinkTemplate('favicon.ico'));
89+
writesFuture.push(writer.symlinkTemplate('main.py'));
9890
}
9991

10092

10193
function now() { return new Date().getTime(); }
10294

10395
function noop() {};
96+

‎docs/src/templates/index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
addTag('script', {src: path('angular-bootstrap.js') }, sync);
4343
addTag('script', {src: path('angular-bootstrap-prettify.js') }, sync);
4444
addTag('script', {src: 'js/docs.js'}, sync);
45-
addTag('script', {src: 'js/docs-keywords.js'}, sync);
45+
addTag('script', {src: 'docs-keywords.js'}, sync);
4646

4747
function path(name) {
4848
if (gae) {

‎docs/src/writer.js

Lines changed: 32 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
*/
55
var qfs = require('q-fs');
66
var Q = require('qq');
7-
var OUTPUT_DIR = "build/docs/";
7+
var OUTPUT_DIR = 'build/docs/';
88
var fs = require('fs');
99

1010
exports.output = output;
@@ -17,29 +17,27 @@ function output(file, content) {
1717
};
1818

1919
//recursively create directory
20-
exports.makeDir = function(path) {
21-
var parts = path.split(/\//);
20+
exports.makeDir = function(p) {
21+
var parts = p.split(/\//);
2222
var path = ".";
23-
//Sequentially create directories
24-
var done = Q.defer();
25-
(function createPart() {
2623

27-
if(!parts.length) {
28-
done.resolve();
29-
} else {
30-
path += "/" + parts.shift();
31-
qfs.isDirectory(path).then(function(isDir) {
32-
if(!isDir) {
33-
qfs.makeDirectory(path);
24+
// Recursively rebuild directory structure
25+
return qfs.exists(p).
26+
then(function createPart(exists) {
27+
if(!exists && parts.length) {
28+
path += "/" + parts.shift();
29+
return qfs.exists(path).then(function(exists) {
30+
if (!exists) {
31+
return qfs.makeDirectory(path).then(createPart, createPart);
32+
} else {
33+
return createPart();
34+
}
35+
});
3436
}
35-
createPart();
3637
});
37-
}
38-
})();
39-
return done.promise;
4038
};
4139

42-
exports.copyTpl = function(filename) {
40+
exports.copyTemplate = function(filename) {
4341
return exports.copy('docs/src/templates/' + filename, filename);
4442
};
4543

@@ -59,8 +57,23 @@ exports.copy = function(from, to, transform) {
5957
}
6058
return output(to, content);
6159
});
60+
};
61+
62+
63+
exports.symlinkTemplate= symlinkTemplate;
64+
function symlinkTemplate(filename) {
65+
var dest = OUTPUT_DIR + filename,
66+
dirDepth = dest.split('/').length,
67+
src = Array(dirDepth).join('../') + 'docs/src/templates/' + filename;
68+
69+
return qfs.exists(dest).then(function(exists) {
70+
if (!exists) {
71+
qfs.symbolicLink(dest, src);
72+
}
73+
});
6274
}
6375

76+
6477
/* Replace placeholders in content accordingly
6578
* @param content{string} content to be modified
6679
* @param replacements{obj} key and value pairs in which key will be replaced with value in content
@@ -132,3 +145,4 @@ exports.toString = function toString(obj) {
132145

133146

134147
function noop() {};
148+

0 commit comments

Comments
 (0)