From e4ed1ce5af12e2f6e7bae59d22a06ab45e620a0e Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 26 Aug 2016 14:58:13 -0700 Subject: [PATCH] chore(site): support site build w/o recompiling API docs (#2202) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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. --- .gitignore | 2 +- gulpfile.js | 102 ++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 77 insertions(+), 27 deletions(-) diff --git a/.gitignore b/.gitignore index 91d27e6acf..679af37907 100644 --- a/.gitignore +++ b/.gitignore @@ -21,7 +21,7 @@ _.* **/resources/zips public/docs/xref-*.* _zip-output -www +www* npm-debug*.log* *.plnkr.html plnkr.html diff --git a/gulpfile.js b/gulpfile.js index 747931fa7a..4cf7e79b5c 100644 --- a/gulpfile.js +++ b/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'; - 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); + 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: [${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)) { - fs.renameSync(oldPath, newPath); + 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}`); } }