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
Ward Bell
parent
907f848c95
commit
e4ed1ce5af
|
|
@ -21,7 +21,7 @@ _.*
|
|||
**/resources/zips
|
||||
public/docs/xref-*.*
|
||||
_zip-output
|
||||
www
|
||||
www*
|
||||
npm-debug*.log*
|
||||
*.plnkr.html
|
||||
plnkr.html
|
||||
|
|
|
|||
94
gulpfile.js
94
gulpfile.js
|
|
@ -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}`);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue