chore(site): support site build w/o recompiling API docs (#2202)

* chore(site): support site build w/o recompiling API docs

If the site has already been built once, then rebuild the site without
re-harp-compiling the API docs use:
`gulp check-deploy —lang=‘’`

Otherwise specify the languages whose API docs are to be rebuilt; as
usual, omitting the `—lang` flag is equivalent to `—lang=all` which is
equivalent to `—lang=‘ts|js|dart’`.

Other changes to gulp tasks:
- Renamed `serve` to `harp-serve`.
- Removed `check-serve`. Use `harp-compile` followed by `serve-www’
instead.
- `harp-compile` now also defaults to `—lang=all`.

* post-review updates

- Ensure that the deploy prompt can be seen.
This commit is contained in:
Patrice Chalin 2016-08-26 14:58:13 -07:00 committed by Ward Bell
parent 907f848c95
commit e4ed1ce5af
2 changed files with 77 additions and 27 deletions

2
.gitignore vendored
View File

@ -21,7 +21,7 @@ _.*
**/resources/zips
public/docs/xref-*.*
_zip-output
www
www*
npm-debug*.log*
*.plnkr.html
plnkr.html

View File

@ -120,22 +120,35 @@ var _styleLessName = 'a2docs.less';
// or a regex pattern to match any one of 'ts', 'js', or 'dart'.
// Default: 'ts|js' except for the "full site build" tasks (see below),
// for which it is 'all'.
//
var lang, langs, buildDartApiDocs = false;
// langs and skipLangs partition ['ts', 'js', 'dart'].
var lang, langs, skipLangs, buildDartApiDocs = false;
function configLangs(langOption) {
const fullSiteBuildTasks = ['build-compile', 'check-serve', 'check-deploy'];
const fullSiteBuildTasks = ['build-compile', 'check-deploy', 'harp-compile'];
const buildAllDocs = argv['_'] &&
fullSiteBuildTasks.some((task) => argv['_'].indexOf(task) >= 0);
const langDefault = buildAllDocs ? 'all' : 'ts|js';
if (langOption === '') {
lang = '';
langs = [];
} else {
lang = (langOption || langDefault).toLowerCase();
if (lang === 'all') lang = 'ts|js|dart';
langs = lang.match(/\w+/g); // the languages in `lang` as an array
gutil.log('Building docs for: ' + lang);
}
gutil.log(`Building docs for: [${langs}]`);
if (langs.indexOf('dart') >= 0) {
buildDartApiDocs = true;
// For Dart, be proactive about checking for the repo
checkAngularProjectPath(ngPathFor('dart'));
} else {
argv.pub = false;
}
skipLangs = [];
['ts', 'js', 'dart'].forEach(lang => {
if (langs.indexOf(lang) < 0) skipLangs.push(lang);
});
gutil.log(`Skipped languages: [${skipLangs}]`);
}
configLangs(argv.lang);
@ -688,12 +701,12 @@ gulp.task('git-changed-examples', ['_shred-devguide-examples'], function(){
});
});
gulp.task('harp-compile', [], function() {
gulp.task('harp-compile', () => {
return harpCompile()
});
gulp.task('serve', [], function() {
// Harp will serve files from workspace.
gulp.task('harp-serve', () => {
// Harp will watch and serve workspace files.
const cmd = 'npm run harp -- server .';
gutil.log('Launching harp server (over project files)');
gutil.log(` > ${cmd}`);
@ -701,7 +714,7 @@ gulp.task('serve', [], function() {
return execPromise(cmd);
});
gulp.task('serve-www', [], function() {
gulp.task('serve-www', () => {
// Serve generated site.
return execPromise('npm run live-server ./www');
});
@ -710,13 +723,6 @@ gulp.task('build-compile', ['build-docs'], function() {
return harpCompile();
});
gulp.task('check-serve', ['build-docs'], function() {
return harpCompile().then(function() {
gutil.log('Launching live-server over ./www');
return execPromise('npm run live-server ./www');
});
});
gulp.task('check-deploy', ['build-docs'], function() {
return harpCompile().then(function() {
gutil.log('compile ok');
@ -812,7 +818,7 @@ gulp.task('_shred-clean-devguide', function(cb) {
gulp.task('_shred-api-examples', ['_shred-clean-api'], function() {
const promises = [];
gutil.log('Shredding API examples for languages: ' + langs.join(', '));
langs.forEach((lang) => {
langs.forEach(lang => {
if (lang === 'js') return; // JS is handled via TS.
checkAngularProjectPath(ngPathFor(lang));
const options = lang == 'dart' ? _apiShredOptionsForDart : _apiShredOptions;
@ -862,26 +868,39 @@ gulp.task('lint', function() {
function harpCompile() {
// Supposedly running in production makes harp faster
// and less likely to drown in node_modules.
env({
vars: { NODE_ENV: "production" }
});
env({ vars: { NODE_ENV: "production" } });
gutil.log("NODE_ENV: " + process.env.NODE_ENV);
if(skipLangs && fs.existsSync('www')) {
gutil.log(`Harp site recompile: skipping recompilation of API docs for [${skipLangs}]`);
gutil.log(`API docs will be copied from existing www folder.`)
del.sync('www-backup'); // remove existing backup if it exists
renameIfExistsSync('www', 'www-backup');
} else {
gutil.log(`Harp full site compile, including API docs for all languages.`);
if (skipLangs)
gutil.log(`Ignoring API docs skip set (${skipLangs}) because full site has not been built yet.`);
}
var deferred = Q.defer();
gutil.log('running harp compile...');
showHideExampleNodeModules('hide');
showHideApiDir('hide');
var spawnInfo = spawnExt('npm',['run','harp', '--', 'compile', '.', './www' ]);
spawnInfo.promise.then(function(x) {
gutil.log("NODE_ENV: " + process.env.NODE_ENV);
showHideExampleNodeModules('show');
showHideApiDir('show');
if (x !== 0) {
deferred.reject(x)
} else {
restoreApiHtml();
deferred.resolve(x);
}
}).catch(function(e) {
gutil.log("NODE_ENV: " + process.env.NODE_ENV);
showHideExampleNodeModules('show');
showHideApiDir('show');
deferred.reject(e);
});
return deferred.promise;
@ -980,6 +999,37 @@ function showHideExampleNodeModules(showOrHide) {
}
}
// Show/hide the API docs harp source folder for every lang in skipLangs.
function showHideApiDir(showOrHide) {
skipLangs.forEach(lang => {
_showHideApiDir(lang, showOrHide);
});
}
// Rename the API docs harp source folder for lang to/from 'api' to '_api-tmp-foo'.
function _showHideApiDir(lang, showOrHide) {
const vers = 'latest';
const basePath = path.join(DOCS_PATH, lang, vers);
const apiDirPath = path.join(basePath, 'api');
const disabledApiDirPath = path.join(basePath, '_api-tmp-hide-from-jade');
const args = showOrHide == 'hide'
? [apiDirPath, disabledApiDirPath]
: [disabledApiDirPath, apiDirPath];
renameIfExistsSync(...args);
}
// For each lang in skipLangs, copy the API dir from www-backup to www.
function restoreApiHtml() {
const vers = 'latest';
skipLangs.forEach(lang => {
const relApiDir = path.join('docs', lang, vers, 'api');
const wwwApiSubdir = path.join('www', relApiDir);
const backupApiSubdir = path.join('www-backup', relApiDir);
gutil.log(`cp ${backupApiSubdir} ${wwwApiSubdir}`)
fs.copySync(backupApiSubdir, wwwApiSubdir);
});
}
// Copies fileNames into destPaths, setting the mode of the
// files at the destination as optional_destFileMode if given.
// returns a promise
@ -1098,11 +1148,10 @@ function watchAndSync(options, cb) {
// returns a promise;
function askDeploy() {
prompt.start();
var schema = {
name: 'shouldDeploy',
description: 'Deploy to Firebase? (y/n): ',
description: 'Deploy to Firebase? (y/n)',
type: 'string',
pattern: /Y|N|y|n/,
message: "Respond with either a 'y' or 'n'",
@ -1467,8 +1516,9 @@ function checkAngularProjectPath(_ngPath) {
function renameIfExistsSync(oldPath, newPath) {
if (fs.existsSync(oldPath)) {
gutil.log(`Rename: mv ${oldPath} ${newPath}`);
fs.renameSync(oldPath, newPath);
} else {
gutil.log(`renameIfExistsSync cannot find file to rename: ${oldPath}`);
gutil.log(`renameIfExistsSync cannot rename, path not found: ${oldPath}`);
}
}