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

Commit 63857f0

Browse files
FoxandxssFoxandxss
committed
chore: ability to generate plunkers for API
1 parent 7252bd1 commit 63857f0

File tree

14 files changed

+301
-30
lines changed

14 files changed

+301
-30
lines changed

‎gulpfile.js

+12-3
Original file line numberDiff line numberDiff line change
@@ -38,15 +38,19 @@ var DOCS_PATH = path.join(PUBLIC_PATH, 'docs');
3838

3939
var EXAMPLES_PATH = path.join(DOCS_PATH, '_examples');
4040
var EXAMPLES_PROTRACTOR_PATH = path.join(EXAMPLES_PATH, '_protractor');
41+
var ANGULAR_EXAMPLES_PATH = path.join(ANGULAR_PROJECT_PATH, 'modules/@angular/examples');
4142
var NOT_API_DOCS_GLOB = path.join(PUBLIC_PATH, './{docs/*/latest/!(api),!(docs)}/**/*.*');
4243
var RESOURCES_PATH = path.join(PUBLIC_PATH, 'resources');
4344
var LIVE_EXAMPLES_PATH = path.join(RESOURCES_PATH, 'live-examples');
45+
var API_LIVE_EXAMPLES_PATH = path.join(RESOURCES_PATH, 'api-live-examples');
4446
var STYLES_SOURCE_PATH = path.join(TOOLS_PATH, 'styles-builder/less');
4547

4648
var docShredder = require(path.resolve(TOOLS_PATH, 'doc-shredder/doc-shredder'));
4749
var exampleZipper = require(path.resolve(TOOLS_PATH, '_example-zipper/exampleZipper'));
4850
var regularPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/regularPlunker'));
4951
var embeddedPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/embeddedPlunker'));
52+
var embeddedApiPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/embeddedApiPlunker'));
53+
var regularApiPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/regularApiPlunker'));
5054
var fsUtils = require(path.resolve(TOOLS_PATH, 'fs-utils/fsUtils'));
5155

5256
const isSilent = !!argv.silent;
@@ -611,7 +615,7 @@ gulp.task('build-docs', ['build-devguide-docs', 'build-api-docs', 'build-plunker
611615
// Stop zipping examples Feb 28, 2016
612616
//gulp.task('build-docs', ['build-devguide-docs', 'build-api-docs', 'build-plunkers', '_zip-examples']);
613617

614-
gulp.task('build-api-docs', ['build-js-api-docs', 'build-ts-api-docs']
618+
gulp.task('build-api-docs', ['build-js-api-docs', 'build-ts-api-docs', 'build-plunkers-api']
615619
.concat(buildDartApiDocs ? ['build-dart-api-docs', 'build-dart-cheatsheet'] : []));
616620

617621
gulp.task('build-devguide-docs', ['_shred-devguide-examples', '_shred-devguide-shared-jade'], function() {
@@ -636,6 +640,11 @@ gulp.task('build-plunkers', ['_copy-example-boilerplate'], function() {
636640
return embeddedPlunker.buildPlunkers(EXAMPLES_PATH, LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build, targetSelf: argv.targetSelf });
637641
});
638642

643+
gulp.task('build-plunkers-api', function() {
644+
regularApiPlunker.buildPlunkers(ANGULAR_EXAMPLES_PATH, API_LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build });
645+
return embeddedApiPlunker.buildPlunkers(ANGULAR_EXAMPLES_PATH, API_LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build });
646+
});
647+
639648
gulp.task('build-dart-cheatsheet', [], function() {
640649
return buildDartCheatsheet();
641650
});
@@ -894,7 +903,7 @@ function harpCompile() {
894903
} else {
895904
gutil.log(`Harp full site compile, including API docs for all languages.`);
896905
if (skipLangs)
897-
gutil.log(`Ignoring API docs skip set (${skipLangs}) because full ` +
906+
gutil.log(`Ignoring API docs skip set (${skipLangs}) because full ` +
898907
`site has not been built yet or some API HTML files are missing.`);
899908
}
900909

@@ -1164,7 +1173,7 @@ function watchAndSync(options, cb) {
11641173

11651174
// When using the --focus=name flag, only **/name/**/*.* example files and
11661175
// **/name.jade files are watched. This is useful for performance reasons.
1167-
// Example: gulp serve-and-sync --focus=architecture
1176+
// Example: gulp serve-and-sync --focus=architecture
11681177
var focus = argv.focus;
11691178

11701179
if (options.devGuide) {

‎public/resources/css/module/_api.scss

+8
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,14 @@ p {
174174
}
175175
}
176176

177+
.api-live-example span {
178+
vertical-align: middle;
179+
cursor: pointer;
180+
}
181+
182+
.api-live-example img {
183+
vertical-align: middle;
184+
}
177185

178186
@media screen and (max-width: 600px) {
179187
.docs-content {

‎public/resources/images/icons/ic_keyboard_arrow_right_black_24px.svg

+4
Loading

‎public/resources/js/directives/live-example.js

+55-11
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,15 @@
2121
*
2222
* <live-example embedded plnkr="minimal"></live-example>
2323
* // ~/resources/live-examples/{chapter}/ts/minimal.eplnkr.html
24+
*
25+
* <live-example api="core/animation/ts/dsl"></live-example>
26+
* // ~/resources/api-live-examples/core/animation/ts/dsl/plnkr.html
27+
*
28+
* <live-example api="core/animation/ts/dsl" embedded></live-example>
29+
* // ~/resources/api-live-examples/core/animation/ts/dsl/eplnkr.html
30+
*
31+
* <live-example api="core/animation/ts/dsl" noimg></live-example>
32+
* // ~/resources/api-live-examples/core/animation/ts/dsl/plnkr.html
2433
*/
2534
angularIO.directive('liveExample', ['$location', function ($location) {
2635

@@ -30,7 +39,18 @@ angularIO.directive('liveExample', ['$location', function ($location) {
3039
return '<a' + attr + '>' + text + '</a>';
3140
}
3241

33-
function span(text) { return '<span>' + text + '</span>'; }
42+
function embeddedNoImgTemplate(src) {
43+
return '<div ng-if="embeddedShow">' +
44+
'<div class="api-live-example" ng-click="toggleEmbedded()" ng-if="embeddedShow">' +
45+
'<img src="/resources/images/icons/ic_keyboard_arrow_down_black_24px.svg"><span>Live example</span>' +
46+
'</div>' +
47+
'<iframe frameborder="0" width="100%" height="100%" src="' + src + '"></iframe>' +
48+
'</div>' +
49+
'<div class="api-live-example" ng-click="toggleEmbedded()" ng-if="!embeddedShow">' +
50+
'<img src="/resources/images/icons/ic_keyboard_arrow_right_black_24px.svg"><span>Live example</span>' +
51+
'</div>'
52+
53+
}
3454

3555
function embeddedTemplate(src, img) {
3656
return '<div ng-if="embeddedShow">' +
@@ -39,6 +59,24 @@ angularIO.directive('liveExample', ['$location', function ($location) {
3959
'<img ng-click="toggleEmbedded()" ng-if="!embeddedShow" src="' + img + '" alt="plunker">';
4060
}
4161

62+
function getHref(langOrApi, example, plnkr) {
63+
var href;
64+
switch (langOrApi) {
65+
case 'ts':
66+
case 'js':
67+
href = '/resources/live-examples/' + example + '/' + langOrApi + '/' + plnkr + '.html';
68+
break;
69+
case 'dart':
70+
href = 'http://angular-examples.github.io/' + example;
71+
break;
72+
case 'api':
73+
href = '/resources/api-live-examples/' + example + '/' + plnkr + '.html';
74+
}
75+
return href;
76+
}
77+
78+
function span(text) { return '<span>' + text + '</span>'; }
79+
4280
return {
4381
restrict: 'E',
4482
scope: true,
@@ -47,35 +85,41 @@ angularIO.directive('liveExample', ['$location', function ($location) {
4785
var ex = attrs.name || NgIoUtil.getExampleName($location);
4886
var embedded = attrs.hasOwnProperty('embedded');
4987
var plnkr = embedded ? 'eplnkr' : 'plnkr';
50-
var href, template;
88+
var href, template, exLang;
5189
var imageBase = '/resources/images/';
5290
var defaultImg = 'plunker/placeholder.png';
53-
91+
var noImg = angular.isDefined(attrs.noimg);
92+
var isApi = !!attrs.api;
93+
console.log(noImg);
5494
if (attrs.plnkr) {
5595
plnkr = attrs.plnkr + '.' + plnkr;
5696
}
5797

98+
if (isApi) {
99+
ex = attrs.api;
100+
exLang = 'api';
101+
} else {
102+
exLang = isForDart ? 'dart' : isForJs ? 'js' : 'ts';
103+
}
104+
58105
var isForDart = attrs.lang === 'dart' || NgIoUtil.isDoc($location, 'dart');
59106
var isForJs = attrs.lang === 'js' || NgIoUtil.isDoc($location, 'js');
60-
var exLang = isForDart ? 'dart' : isForJs ? 'js' : 'ts';
61107

62108
if (embedded && !isForDart) {
63-
href = '/resources/live-examples/' + ex + '/' + exLang + '/' + plnkr + '.html';
109+
href = getHref(exLang, ex, plnkr);
64110
img = imageBase + (attrs.img || defaultImg);
65-
template = embeddedTemplate(href, img);
111+
template = noImg ? embeddedNoImgTemplate(href) : embeddedTemplate(href, img);
66112
} else {
67-
var href = isForDart
68-
? 'http://angular-examples.github.io/' + ex
69-
: '/resources/live-examples/' + ex + '/' + exLang + '/' + plnkr + '.html'
113+
href = getHref(exLang, ex, plnkr);
70114

71115
// Link to live example.
72-
var template = a(text, { href: href, target: '_blank' });
116+
template = a(text, { href: href, target: '_blank' });
73117

74118
// The hosted example and sources are in different locations for Dart.
75119
// Also show link to sources for Dart, unless noSource is specified.
76120
if (isForDart && !attrs.hasOwnProperty('nosource')) {
77121
var srcText = attrs.srcText || 'view source';
78-
var srcHref = 'http://github.com/angular-examples/' + ex;
122+
href = getHref('dart', ex);
79123
template = span(template + ' (' + a(srcText, { href: srcHref, target: '_blank' }) + ')');
80124
}
81125
}

‎tools/api-builder/angular.io-package/rendering/indentForMarkdown.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -59,4 +59,4 @@ module.exports = function(encodeCodeBlock) {
5959
return str;
6060
};
6161

62-
};
62+
};

‎tools/api-builder/links-package/index.js

+3-1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ module.exports = new Package('links', [])
66
.factory(require('./inline-tag-defs/linkDocs'))
77
.factory(require('./inline-tag-defs/example'))
88
.factory(require('./inline-tag-defs/exampleTabs'))
9+
.factory(require('./inline-tag-defs/liveExample'))
910
.factory(require('dgeni-packages/links/services/getAliases'))
1011
.factory(require('dgeni-packages/links/services/getDocFromAlias'))
1112
.factory(require('./services/getLinkInfo'))
@@ -14,11 +15,12 @@ module.exports = new Package('links', [])
1415
.factory(require('./services/deprecatedDocsLinkDisambiguator'))
1516
.factory(require('./services/getApiFragmentFileName'))
1617

17-
.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) {
18+
.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef, liveExampleInlineTagDef) {
1819
inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
1920
inlineTagProcessor.inlineTagDefinitions.push(linkDocsInlineTagDef);
2021
inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef);
2122
inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef);
23+
inlineTagProcessor.inlineTagDefinitions.push(liveExampleInlineTagDef);
2224
})
2325

2426
.config(function(getLinkInfo, moduleScopeLinkDisambiguator, deprecatedDocsLinkDisambiguator) {

‎tools/api-builder/links-package/inline-tag-defs/liveExample.js

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
var path = require('canonical-path');
2+
var fs = require("fs");
3+
4+
/**
5+
* @dgService liveExampleInlineTagDef
6+
* @description
7+
* Process inline liveExample tags (of the form {@liveExample demo-path embedded }),
8+
* replacing them with a <live-example> directive.
9+
* Examples:
10+
* {@liveExample core/animation/ts/dsl }
11+
* {@liveExample core/di/ts/contentChildren embedded }
12+
* @kind function
13+
*/
14+
module.exports = function liveExampleInlineTagDef(getLinkInfo, parseArgString, getApiFragmentFileName, createDocMessage, log) {
15+
return {
16+
name: 'liveExample',
17+
description: 'Process inline liveExample tags (of the form {@liveExample demo-path embedded }), replacing them with <live-example>',
18+
handler: function(doc, tagName, tagDescription) {
19+
20+
var tagArgs = parseArgString(tagDescription);
21+
var unnamedArgs = tagArgs._;
22+
var relativePath = unnamedArgs[0] !== 'embedded' ? unnamedArgs[0] : unnamedArgs[1];
23+
var embedded = unnamedArgs.indexOf('embedded') >= 0 ? 'embedded' : '';
24+
var imgPath = tagArgs.img;
25+
26+
// check if fragment file actually exists.
27+
var apiPlunkerFile = getApiPlunkerFile(relativePath);
28+
if ( !fs.existsSync(apiPlunkerFile)) {
29+
log.warn(createDocMessage(`Invalid example (unable to locate plunker file: ${apiPlunkerFile}`));
30+
}
31+
32+
return [ `<live-example api="${relativePath}" ${embedded} ${imgPath ? `img="${imgPath}"` : 'noimg'}></live-example>` ];
33+
}
34+
};
35+
};
36+
37+
function getApiPlunkerFile(relativePath) {
38+
return path.join('/resources/api-live-examples', `${relativePath}/plnkr.html`);
39+
}

‎tools/plunker-builder/boilerplate/index.html

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="UTF-8">
5+
<title>Animations</title>
6+
<meta name="viewport" content="width=device-width, initial-scale=1">
7+
8+
<!-- Polyfill for Web Animations -->
9+
<script src="https://unpkg.com/[email protected]"></script>
10+
11+
<!-- Polyfill(s) for older browsers -->
12+
<script src="https://unpkg.com/core-js/client/shim.min.js"></script>
13+
14+
<script src="https://unpkg.com/[email protected]?main=browser"></script>
15+
<script src="https://unpkg.com/[email protected]"></script>
16+
<script src="https://unpkg.com/[email protected]/dist/system.src.js"></script>
17+
18+
<script src="systemjs.config.js"></script>
19+
<script>
20+
System.import('app').catch(function(err){ console.error(err); });
21+
</script>
22+
</head>
23+
24+
<body>
25+
<example-app>
26+
Loading...
27+
</example-app>
28+
</body>
29+
30+
</html>

‎tools/plunker-builder/boilerplate/main.ts

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
2+
3+
import { AppModule } from './module.ts';
4+
5+
platformBrowserDynamic().bootstrapModule(AppModule);

0 commit comments

Comments
 (0)