Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

Commit 45ac0ee

Browse files
jtrabandwardbell
jtraband
authored and
wardbell
committed
docs(tooling): new mixin for sharing jade files
merges #725
1 parent cca9d5a commit 45ac0ee

File tree

5 files changed

+183
-6
lines changed

5 files changed

+183
-6
lines changed

‎gulpfile.js‎

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,11 @@ var _devguideShredOptions = {
4949
zipDir: path.join(RESOURCES_PATH, 'zips')
5050
};
5151

52+
var _devguideShredJadeOptions = {
53+
jadeDir: DOCS_PATH
54+
55+
};
56+
5257
var _apiShredOptions = {
5358
examplesDir: path.join(ANGULAR_PROJECT_PATH, 'modules/angular2/examples'),
5459
fragmentsDir: path.join(DOCS_PATH, '_fragments/_api'),
@@ -260,15 +265,20 @@ gulp.task('remove-example-boilerplate', function() {
260265
});
261266

262267
gulp.task('serve-and-sync', ['build-docs'], function (cb) {
263-
watchAndSync({devGuide: true, apiDocs: true, apiExamples: true, localFiles: true}, cb);
268+
// watchAndSync({devGuide: true, apiDocs: true, apiExamples: true, localFiles: true}, cb);
269+
watchAndSync({devGuide: true, devGuideJade: true, apiDocs: true, apiExamples: true, localFiles: true}, cb);
264270
});
265271

266272
gulp.task('serve-and-sync-api', ['build-docs'], function (cb) {
267273
watchAndSync({apiDocs: true, apiExamples: true}, cb);
268274
});
269275

270-
gulp.task('serve-and-sync-devguide', ['build-devguide-docs', 'build-plunkers', '_zip-examples'], function (cb) {
271-
watchAndSync({devGuide: true, localFiles: true}, cb);
276+
gulp.task('serve-and-sync-devguide', ['build-devguide-docs', 'build-plunkers' ], function (cb) {
277+
watchAndSync({devGuide: true, devGuideJade: true, localFiles: true}, cb);
278+
});
279+
280+
gulp.task('_serve-and-sync-jade', function (cb) {
281+
watchAndSync({devGuideJade: true, localFiles: true}, cb);
272282
});
273283

274284
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
279289

280290
gulp.task('build-api-docs', ['build-js-api-docs', 'build-ts-api-docs', 'build-dart-cheatsheet']);
281291

282-
gulp.task('build-devguide-docs', ['_shred-devguide-examples'], function() {
292+
gulp.task('build-devguide-docs', ['_shred-devguide-examples', '_shred-devguide-shared-jade'], function() {
283293
return buildShredMaps(true);
284294
});
285295

@@ -384,6 +394,15 @@ gulp.task('_shred-devguide-examples', ['_shred-clean-devguide'], function() {
384394
return docShredder.shred( _devguideShredOptions);
385395
});
386396

397+
gulp.task('_shred-devguide-shared-jade', ['_shred-clean-devguide-shared-jade'], function() {
398+
return docShredder.shred( _devguideShredJadeOptions);
399+
});
400+
401+
gulp.task('_shred-clean-devguide-shared-jade', function(cb) {
402+
var cleanPath = path.join(DOCS_PATH, '**/_.*.jade')
403+
return delPromise([ cleanPath]);
404+
});
405+
387406
gulp.task('_shred-clean-devguide', function(cb) {
388407
var cleanPath = path.join(_devguideShredOptions.fragmentsDir, '**/*.*')
389408
return delPromise([ cleanPath, '!**/*.ovr.*', '!**/_api/**']);
@@ -523,6 +542,9 @@ function watchAndSync(options, cb) {
523542
if (options.devGuide) {
524543
devGuideExamplesWatch(_devguideShredOptions, browserSync.reload);
525544
}
545+
if (options.devGuideJade) {
546+
devGuideSharedJadeWatch( { jadeDir: DOCS_PATH}, browserSync.reload);
547+
}
526548
if (options.apiDocs) {
527549
apiSourceWatch(browserSync.reload);
528550
}
@@ -603,6 +625,20 @@ function devGuideExamplesWatch(shredOptions, postShredAction) {
603625
});
604626
}
605627

628+
function devGuideSharedJadeWatch(shredOptions, postShredAction) {
629+
var includePattern = path.join(DOCS_PATH, '**/*.jade');
630+
var excludePattern = '!' + path.join(shredOptions.jadeDir, '**/node_modules/**/*.*');
631+
// removed this version because gulp.watch has the same glob issue that dgeni has.
632+
// gulp.watch([includePattern, excludePattern], {readDelay: 500}, function (event, done) {
633+
var files = globby.sync( [includePattern], { ignore: [ '**/node_modules/**']});
634+
gulp.watch([files], {readDelay: 500}, function (event, done) {
635+
gutil.log('Dev Guide jade file changed')
636+
gutil.log('Event type: ' + event.type); // added, changed, or deleted
637+
gutil.log('Event path: ' + event.path); // The path of the modified file
638+
return docShredder.shredSingleJadeDir(shredOptions, event.path).then(postShredAction);
639+
});
640+
}
641+
606642

607643
// Generate the API docs for the specified language, if not specified then it defaults to ts
608644
function buildApiDocs(targetLanguage) {

‎public/_includes/_util-fns.jade‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
//- Mixins and associated functions
22
3+
mixin includeShared(filePath, region)
4+
- var newPath = translatePath(filePath, region);
5+
!=partial(newPath)
6+
37
mixin makeExample(filePath, region, title, stylePatterns)
48
- var language = attributes.language || getExtn(filePath);
59
- var frag = getFrag(filePath, region);
@@ -44,6 +48,27 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns)
4448

4549

4650
//---------------------------------------------------------------------------------------------------------
51+
- var translatePath = function(filePath, region) {
52+
- filePath = filePath.trim();
53+
- var regionPad = (region && region.length) ? '-' + region.toString() : '';
54+
- var matches = /{(.*)}.*/.exec(filePath);
55+
- if (matches) {
56+
- var topLevelDir = matches[1];
57+
- var currentPath = current.path;
58+
- var subPaths = currentPath.slice(2);
59+
- subPaths[subPaths.length - 1] = "_." + subPaths[subPaths.length - 1];
60+
- var newPath = getPathToDocs() + topLevelDir + '/' + subPaths.join("/");
61+
- var result = newPath + regionPad + ".jade";
62+
- } else {
63+
- var extn = getExtn(filePath);
64+
- var baseFileName = getBaseFileName(filePath);
65+
- var noExtnFileName = baseFileName.substr(0,baseFileName.length - (extn.length + 1));
66+
- var folder = getFolder(filePath);
67+
- var result = folder + "/_." + noExtnFileName + regionPad + "." + extn;
68+
- }
69+
- return result
70+
- }
71+
4772

4873
- var EMPTY_STRINGS = [ '','','','','','',''];
4974

@@ -146,6 +171,16 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns)
146171
- return ix > 0 ? fileName.substr(ix+1) : "";
147172
- }
148173

174+
- var getBaseFileName = function(fileName) {
175+
- var ix = fileName.lastIndexOf('/');
176+
- return ix > 0 ? fileName.substr(ix+1) : "";
177+
- }
178+
179+
- var getFolder = function(fileName) {
180+
- var ix = fileName.lastIndexOf('/');
181+
- return ix > 0 ? fileName.substr(0, ix) : "";
182+
- }
183+
149184
- var getPathToDocs = function() {
150185
- // simple way to only take as many '../' sections as we need to back up to the 'docs' dir
151186
- // from the current document

‎tools/doc-shredder/doc-shredder.js‎

Lines changed: 78 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,12 @@ var globby = require('globby');
1010

1111
var shred = function(shredOptions) {
1212
try {
13-
var pkg = createShredPackage(shredOptions);
13+
var pkg;
14+
if (shredOptions.jadeDir) {
15+
pkg = createShredJadePackage(shredOptions);
16+
} else {
17+
pkg = createShredExamplePackage(shredOptions);
18+
}
1419
var dgeni = new Dgeni([ pkg]);
1520
return dgeni.generate();
1621
} catch(err) {
@@ -38,6 +43,23 @@ var shredSingleDir = function(shredOptions, filePath) {
3843
});
3944
}
4045

46+
var shredSingleJadeDir = function(shredOptions, filePath) {
47+
shredOptions = resolveShredOptions(shredOptions);
48+
var fileDir = path.dirname(filePath);
49+
var relativePath = path.relative(shredOptions.jadeDir, fileDir);
50+
var jadeDir = path.join(shredOptions.jadeDir, relativePath);
51+
52+
var options = {
53+
includeSubdirs: false,
54+
jadeDir: jadeDir
55+
}
56+
var cleanPath = path.join(jadeDir, '_.*.jade')
57+
return delPromise([ cleanPath]).then(function(paths) {
58+
console.log('Deleted files/folders:\n', paths.join('\n'));
59+
return shred(options);
60+
});
61+
}
62+
4163
var buildShredMap = function(shredMapOptions) {
4264
try {
4365
var pkg = createShredMapPackage(shredMapOptions);
@@ -53,10 +75,11 @@ var buildShredMap = function(shredMapOptions) {
5375
module.exports = {
5476
shred: shred,
5577
shredSingleDir: shredSingleDir,
78+
shredSingleJadeDir: shredSingleJadeDir,
5679
buildShredMap: buildShredMap
5780
};
5881

59-
function createShredPackage(shredOptions) {
82+
function createShredExamplePackage(shredOptions) {
6083
var pkg = new Dgeni.Package('doc-shredder', [
6184
// require('dgeni-packages/base') - doesn't work
6285
]);
@@ -105,6 +128,59 @@ function createShredPackage(shredOptions) {
105128
return pkg;
106129
}
107130

131+
function createShredJadePackage(shredOptions) {
132+
var pkg = new Dgeni.Package('jade-doc-shredder', [
133+
// require('dgeni-packages/base') - doesn't work
134+
]);
135+
136+
var options = shredOptions;
137+
options.jadeDir = path.resolve(options.jadeDir);
138+
options.includeSubdirs = options.includeSubdirs == null ? true : options.includeSubdirs;
139+
140+
initializePackage(pkg)
141+
.factory(require('./fileReaders/regionFileReader'))
142+
.processor(require('./processors/renderAsJadeProcessor'))
143+
144+
.config(function(readFilesProcessor, regionFileReader) {
145+
readFilesProcessor.fileReaders = [regionFileReader];
146+
})
147+
// default configs - may be overridden
148+
.config(function(readFilesProcessor) {
149+
// Specify the base path used when resolving relative paths to source and output files
150+
readFilesProcessor.basePath = "/";
151+
152+
// Specify collections of source files that should contain the documentation to extract
153+
var extns = ['*.jade' ];
154+
var includeFiles = extns.map(function(extn) {
155+
if (options.includeSubdirs) {
156+
return path.join(options.jadeDir, '**', extn);
157+
} else {
158+
return path.join(options.jadeDir, extn);
159+
}
160+
});
161+
162+
// HACK ( next two lines) because the glob function that dgeni uses internally isn't good at removing 'node_modules' early
163+
// this just uses globby to 'preglob' the include files ( and exclude the node_modules).
164+
var nmPattern = '**/node_modules/**';
165+
var includeFiles = globby.sync( includeFiles, { ignore: [nmPattern] } );
166+
167+
readFilesProcessor.sourceFiles = [ {
168+
// Process all candidate files in `src` and its subfolders ...
169+
include: includeFiles ,
170+
exclude: [ '**/node_modules/**', '**/typings/**', '**/packages/**', '**/build/**', '**/_code-examples.jade'],
171+
// When calculating the relative path to these files use this as the base path.
172+
// So `src/foo/bar.js` will have relative path of `foo/bar.js`
173+
basePath: options.jadeDir
174+
} ];
175+
})
176+
.config(function(writeFilesProcessor) {
177+
// Specify where the writeFilesProcessor will write our generated doc files
178+
writeFilesProcessor.outputFolder = '.';
179+
});
180+
return pkg;
181+
}
182+
183+
108184
var createShredMapPackage = function(mapOptions) {
109185
var pkg = new Dgeni.Package('doc-shred-mapper', [
110186
require('dgeni-packages/base'),

‎tools/doc-shredder/processors/renderAsJadeProcessor.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
var path = require('canonical-path');
2+
/**
3+
* dgProcessor
4+
* @description
5+
*
6+
*/
7+
module.exports = function renderAsJadeProcessor() {
8+
return {
9+
$runAfter: ['readFilesProcessor'],
10+
$runBefore: ['writing-files'],
11+
$process: function(docs) {
12+
return docs.map(function(doc) {
13+
var fileInfo = doc.fileInfo;
14+
doc.renderedContent = doc.content ;
15+
var regionSuffix = (doc.regionName && doc.regionName.length) ? "-" + doc.regionName.trim() : "";
16+
var origName = fileInfo.baseName + "." + fileInfo.extension;
17+
18+
var newName = "_." + fileInfo.baseName + regionSuffix + "." + fileInfo.extension;
19+
doc.outputPath = fileInfo.filePath.replace(origName, newName);
20+
return doc;
21+
})
22+
}
23+
};
24+
};

‎tools/doc-shredder/regionExtractor.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,12 @@ function getCommentInfo(extension) {
180180
plasterPattern: '# {tag} '
181181
};
182182
break;
183+
case 'jade':
184+
commentInfo = {
185+
prefix: '//',
186+
plasterPattern: '// {tag} '
187+
};
188+
break;
183189
default:
184190
return null;
185191
}

0 commit comments

Comments
 (0)