From 45ac0ee37dd0f0075fed9ba23a24ebc692de1d4f Mon Sep 17 00:00:00 2001 From: Jay Traband Date: Tue, 19 Jan 2016 02:11:58 -0800 Subject: [PATCH] docs(tooling): new mixin for sharing jade files merges #725 --- gulpfile.js | 44 +++++++++- public/_includes/_util-fns.jade | 35 ++++++++ tools/doc-shredder/doc-shredder.js | 80 ++++++++++++++++++- .../processors/renderAsJadeProcessor.js | 24 ++++++ tools/doc-shredder/regionExtractor.js | 6 ++ 5 files changed, 183 insertions(+), 6 deletions(-) create mode 100644 tools/doc-shredder/processors/renderAsJadeProcessor.js diff --git a/gulpfile.js b/gulpfile.js index 5f61709aa1..fda5aa1e2b 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -49,6 +49,11 @@ var _devguideShredOptions = { zipDir: path.join(RESOURCES_PATH, 'zips') }; +var _devguideShredJadeOptions = { + jadeDir: DOCS_PATH + +}; + var _apiShredOptions = { examplesDir: path.join(ANGULAR_PROJECT_PATH, 'modules/angular2/examples'), fragmentsDir: path.join(DOCS_PATH, '_fragments/_api'), @@ -260,15 +265,20 @@ gulp.task('remove-example-boilerplate', function() { }); gulp.task('serve-and-sync', ['build-docs'], function (cb) { - watchAndSync({devGuide: true, apiDocs: true, apiExamples: true, localFiles: true}, cb); + // watchAndSync({devGuide: true, apiDocs: true, apiExamples: true, localFiles: true}, cb); + watchAndSync({devGuide: true, devGuideJade: true, apiDocs: true, apiExamples: true, localFiles: true}, cb); }); gulp.task('serve-and-sync-api', ['build-docs'], function (cb) { watchAndSync({apiDocs: true, apiExamples: true}, cb); }); -gulp.task('serve-and-sync-devguide', ['build-devguide-docs', 'build-plunkers', '_zip-examples'], function (cb) { - watchAndSync({devGuide: true, localFiles: true}, cb); +gulp.task('serve-and-sync-devguide', ['build-devguide-docs', 'build-plunkers' ], function (cb) { + watchAndSync({devGuide: true, devGuideJade: true, localFiles: true}, cb); +}); + +gulp.task('_serve-and-sync-jade', function (cb) { + watchAndSync({devGuideJade: true, localFiles: true}, cb); }); gulp.task('build-and-serve', ['build-docs'], function (cb) { @@ -279,7 +289,7 @@ gulp.task('build-docs', ['build-devguide-docs', 'build-api-docs', 'build-plunker gulp.task('build-api-docs', ['build-js-api-docs', 'build-ts-api-docs', 'build-dart-cheatsheet']); -gulp.task('build-devguide-docs', ['_shred-devguide-examples'], function() { +gulp.task('build-devguide-docs', ['_shred-devguide-examples', '_shred-devguide-shared-jade'], function() { return buildShredMaps(true); }); @@ -384,6 +394,15 @@ gulp.task('_shred-devguide-examples', ['_shred-clean-devguide'], function() { return docShredder.shred( _devguideShredOptions); }); +gulp.task('_shred-devguide-shared-jade', ['_shred-clean-devguide-shared-jade'], function() { + return docShredder.shred( _devguideShredJadeOptions); +}); + +gulp.task('_shred-clean-devguide-shared-jade', function(cb) { + var cleanPath = path.join(DOCS_PATH, '**/_.*.jade') + return delPromise([ cleanPath]); +}); + gulp.task('_shred-clean-devguide', function(cb) { var cleanPath = path.join(_devguideShredOptions.fragmentsDir, '**/*.*') return delPromise([ cleanPath, '!**/*.ovr.*', '!**/_api/**']); @@ -523,6 +542,9 @@ function watchAndSync(options, cb) { if (options.devGuide) { devGuideExamplesWatch(_devguideShredOptions, browserSync.reload); } + if (options.devGuideJade) { + devGuideSharedJadeWatch( { jadeDir: DOCS_PATH}, browserSync.reload); + } if (options.apiDocs) { apiSourceWatch(browserSync.reload); } @@ -603,6 +625,20 @@ function devGuideExamplesWatch(shredOptions, postShredAction) { }); } +function devGuideSharedJadeWatch(shredOptions, postShredAction) { + var includePattern = path.join(DOCS_PATH, '**/*.jade'); + var excludePattern = '!' + path.join(shredOptions.jadeDir, '**/node_modules/**/*.*'); + // removed this version because gulp.watch has the same glob issue that dgeni has. + // gulp.watch([includePattern, excludePattern], {readDelay: 500}, function (event, done) { + var files = globby.sync( [includePattern], { ignore: [ '**/node_modules/**']}); + gulp.watch([files], {readDelay: 500}, function (event, done) { + gutil.log('Dev Guide jade file changed') + gutil.log('Event type: ' + event.type); // added, changed, or deleted + gutil.log('Event path: ' + event.path); // The path of the modified file + return docShredder.shredSingleJadeDir(shredOptions, event.path).then(postShredAction); + }); +} + // Generate the API docs for the specified language, if not specified then it defaults to ts function buildApiDocs(targetLanguage) { diff --git a/public/_includes/_util-fns.jade b/public/_includes/_util-fns.jade index df54bcc1f9..da27732e32 100644 --- a/public/_includes/_util-fns.jade +++ b/public/_includes/_util-fns.jade @@ -1,5 +1,9 @@ //- Mixins and associated functions +mixin includeShared(filePath, region) + - var newPath = translatePath(filePath, region); + !=partial(newPath) + mixin makeExample(filePath, region, title, stylePatterns) - var language = attributes.language || getExtn(filePath); - var frag = getFrag(filePath, region); @@ -44,6 +48,27 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns) //--------------------------------------------------------------------------------------------------------- +- var translatePath = function(filePath, region) { +- filePath = filePath.trim(); +- var regionPad = (region && region.length) ? '-' + region.toString() : ''; +- var matches = /{(.*)}.*/.exec(filePath); +- if (matches) { +- var topLevelDir = matches[1]; +- var currentPath = current.path; +- var subPaths = currentPath.slice(2); +- subPaths[subPaths.length - 1] = "_." + subPaths[subPaths.length - 1]; +- var newPath = getPathToDocs() + topLevelDir + '/' + subPaths.join("/"); +- var result = newPath + regionPad + ".jade"; +- } else { +- var extn = getExtn(filePath); +- var baseFileName = getBaseFileName(filePath); +- var noExtnFileName = baseFileName.substr(0,baseFileName.length - (extn.length + 1)); +- var folder = getFolder(filePath); +- var result = folder + "/_." + noExtnFileName + regionPad + "." + extn; +- } +- return result +- } + - var EMPTY_STRINGS = [ '','','','','','','']; @@ -146,6 +171,16 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns) - return ix > 0 ? fileName.substr(ix+1) : ""; - } +- var getBaseFileName = function(fileName) { +- var ix = fileName.lastIndexOf('/'); +- return ix > 0 ? fileName.substr(ix+1) : ""; +- } + +- var getFolder = function(fileName) { +- var ix = fileName.lastIndexOf('/'); +- return ix > 0 ? fileName.substr(0, ix) : ""; +- } + - var getPathToDocs = function() { - // simple way to only take as many '../' sections as we need to back up to the 'docs' dir - // from the current document diff --git a/tools/doc-shredder/doc-shredder.js b/tools/doc-shredder/doc-shredder.js index 1df060a3ea..4d4698055a 100644 --- a/tools/doc-shredder/doc-shredder.js +++ b/tools/doc-shredder/doc-shredder.js @@ -10,7 +10,12 @@ var globby = require('globby'); var shred = function(shredOptions) { try { - var pkg = createShredPackage(shredOptions); + var pkg; + if (shredOptions.jadeDir) { + pkg = createShredJadePackage(shredOptions); + } else { + pkg = createShredExamplePackage(shredOptions); + } var dgeni = new Dgeni([ pkg]); return dgeni.generate(); } catch(err) { @@ -38,6 +43,23 @@ var shredSingleDir = function(shredOptions, filePath) { }); } +var shredSingleJadeDir = function(shredOptions, filePath) { + shredOptions = resolveShredOptions(shredOptions); + var fileDir = path.dirname(filePath); + var relativePath = path.relative(shredOptions.jadeDir, fileDir); + var jadeDir = path.join(shredOptions.jadeDir, relativePath); + + var options = { + includeSubdirs: false, + jadeDir: jadeDir + } + var cleanPath = path.join(jadeDir, '_.*.jade') + return delPromise([ cleanPath]).then(function(paths) { + console.log('Deleted files/folders:\n', paths.join('\n')); + return shred(options); + }); +} + var buildShredMap = function(shredMapOptions) { try { var pkg = createShredMapPackage(shredMapOptions); @@ -53,10 +75,11 @@ var buildShredMap = function(shredMapOptions) { module.exports = { shred: shred, shredSingleDir: shredSingleDir, + shredSingleJadeDir: shredSingleJadeDir, buildShredMap: buildShredMap }; -function createShredPackage(shredOptions) { +function createShredExamplePackage(shredOptions) { var pkg = new Dgeni.Package('doc-shredder', [ // require('dgeni-packages/base') - doesn't work ]); @@ -105,6 +128,59 @@ function createShredPackage(shredOptions) { return pkg; } +function createShredJadePackage(shredOptions) { + var pkg = new Dgeni.Package('jade-doc-shredder', [ + // require('dgeni-packages/base') - doesn't work + ]); + + var options = shredOptions; + options.jadeDir = path.resolve(options.jadeDir); + options.includeSubdirs = options.includeSubdirs == null ? true : options.includeSubdirs; + + initializePackage(pkg) + .factory(require('./fileReaders/regionFileReader')) + .processor(require('./processors/renderAsJadeProcessor')) + + .config(function(readFilesProcessor, regionFileReader) { + readFilesProcessor.fileReaders = [regionFileReader]; + }) + // default configs - may be overridden + .config(function(readFilesProcessor) { + // Specify the base path used when resolving relative paths to source and output files + readFilesProcessor.basePath = "/"; + + // Specify collections of source files that should contain the documentation to extract + var extns = ['*.jade' ]; + var includeFiles = extns.map(function(extn) { + if (options.includeSubdirs) { + return path.join(options.jadeDir, '**', extn); + } else { + return path.join(options.jadeDir, extn); + } + }); + + // HACK ( next two lines) because the glob function that dgeni uses internally isn't good at removing 'node_modules' early + // this just uses globby to 'preglob' the include files ( and exclude the node_modules). + var nmPattern = '**/node_modules/**'; + var includeFiles = globby.sync( includeFiles, { ignore: [nmPattern] } ); + + readFilesProcessor.sourceFiles = [ { + // Process all candidate files in `src` and its subfolders ... + include: includeFiles , + exclude: [ '**/node_modules/**', '**/typings/**', '**/packages/**', '**/build/**', '**/_code-examples.jade'], + // When calculating the relative path to these files use this as the base path. + // So `src/foo/bar.js` will have relative path of `foo/bar.js` + basePath: options.jadeDir + } ]; + }) + .config(function(writeFilesProcessor) { + // Specify where the writeFilesProcessor will write our generated doc files + writeFilesProcessor.outputFolder = '.'; + }); + return pkg; +} + + var createShredMapPackage = function(mapOptions) { var pkg = new Dgeni.Package('doc-shred-mapper', [ require('dgeni-packages/base'), diff --git a/tools/doc-shredder/processors/renderAsJadeProcessor.js b/tools/doc-shredder/processors/renderAsJadeProcessor.js new file mode 100644 index 0000000000..b9df9994d2 --- /dev/null +++ b/tools/doc-shredder/processors/renderAsJadeProcessor.js @@ -0,0 +1,24 @@ +var path = require('canonical-path'); +/** + * dgProcessor + * @description + * + */ +module.exports = function renderAsJadeProcessor() { + return { + $runAfter: ['readFilesProcessor'], + $runBefore: ['writing-files'], + $process: function(docs) { + return docs.map(function(doc) { + var fileInfo = doc.fileInfo; + doc.renderedContent = doc.content ; + var regionSuffix = (doc.regionName && doc.regionName.length) ? "-" + doc.regionName.trim() : ""; + var origName = fileInfo.baseName + "." + fileInfo.extension; + + var newName = "_." + fileInfo.baseName + regionSuffix + "." + fileInfo.extension; + doc.outputPath = fileInfo.filePath.replace(origName, newName); + return doc; + }) + } + }; +}; \ No newline at end of file diff --git a/tools/doc-shredder/regionExtractor.js b/tools/doc-shredder/regionExtractor.js index d73b25c4ae..870c3620a0 100644 --- a/tools/doc-shredder/regionExtractor.js +++ b/tools/doc-shredder/regionExtractor.js @@ -180,6 +180,12 @@ function getCommentInfo(extension) { plasterPattern: '# {tag} ' }; break; + case 'jade': + commentInfo = { + prefix: '//', + plasterPattern: '// {tag} ' + }; + break; default: return null; }