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

Commit

Permalink
chore: ability to generate plunkers for API
Browse files Browse the repository at this point in the history
  • Loading branch information
Foxandxss committed Sep 20, 2016
1 parent 40f320d commit aa9560d
Show file tree
Hide file tree
Showing 14 changed files with 301 additions and 30 deletions.
15 changes: 12 additions & 3 deletions gulpfile.js
Original file line number Diff line number Diff line change
Expand Up @@ -38,15 +38,19 @@ var DOCS_PATH = path.join(PUBLIC_PATH, 'docs');

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

var docShredder = require(path.resolve(TOOLS_PATH, 'doc-shredder/doc-shredder'));
var exampleZipper = require(path.resolve(TOOLS_PATH, '_example-zipper/exampleZipper'));
var regularPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/regularPlunker'));
var embeddedPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/embeddedPlunker'));
var embeddedApiPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/embeddedApiPlunker'));
var regularApiPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/regularApiPlunker'));
var fsUtils = require(path.resolve(TOOLS_PATH, 'fs-utils/fsUtils'));

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

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

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

gulp.task('build-plunkers-api', function() {
regularApiPlunker.buildPlunkers(ANGULAR_EXAMPLES_PATH, API_LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build });
return embeddedApiPlunker.buildPlunkers(ANGULAR_EXAMPLES_PATH, API_LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build });
});

gulp.task('build-dart-cheatsheet', [], function() {
return buildDartCheatsheet();
});
Expand Down Expand Up @@ -894,7 +903,7 @@ function harpCompile() {
} 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 ` +
gutil.log(`Ignoring API docs skip set (${skipLangs}) because full ` +
`site has not been built yet or some API HTML files are missing.`);
}

Expand Down Expand Up @@ -1164,7 +1173,7 @@ function watchAndSync(options, cb) {

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

if (options.devGuide) {
Expand Down
8 changes: 8 additions & 0 deletions public/resources/css/module/_api.scss
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,14 @@ p {
}
}

.api-live-example span {
vertical-align: middle;
cursor: pointer;
}

.api-live-example img {
vertical-align: middle;
}

@media screen and (max-width: 600px) {
.docs-content {
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
66 changes: 55 additions & 11 deletions public/resources/js/directives/live-example.js
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,15 @@
*
* <live-example embedded plnkr="minimal"></live-example>
* // ~/resources/live-examples/{chapter}/ts/minimal.eplnkr.html
*
* <live-example api="core/animation/ts/dsl"></live-example>
* // ~/resources/api-live-examples/core/animation/ts/dsl/plnkr.html
*
* <live-example api="core/animation/ts/dsl" embedded></live-example>
* // ~/resources/api-live-examples/core/animation/ts/dsl/eplnkr.html
*
* <live-example api="core/animation/ts/dsl" noimg></live-example>
* // ~/resources/api-live-examples/core/animation/ts/dsl/plnkr.html
*/
angularIO.directive('liveExample', ['$location', function ($location) {

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

function span(text) { return '<span>' + text + '</span>'; }
function embeddedNoImgTemplate(src) {
return '<div ng-if="embeddedShow">' +
'<div class="api-live-example" ng-click="toggleEmbedded()" ng-if="embeddedShow">' +
'<img src="/resources/images/icons/ic_keyboard_arrow_down_black_24px.svg"><span>Live example</span>' +
'</div>' +
'<iframe frameborder="0" width="100%" height="100%" src="' + src + '"></iframe>' +
'</div>' +
'<div class="api-live-example" ng-click="toggleEmbedded()" ng-if="!embeddedShow">' +
'<img src="/resources/images/icons/ic_keyboard_arrow_right_black_24px.svg"><span>Live example</span>' +
'</div>'

}

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

function getHref(langOrApi, example, plnkr) {
var href;
switch (langOrApi) {
case 'ts':
case 'js':
href = '/resources/live-examples/' + example + '/' + langOrApi + '/' + plnkr + '.html';
break;
case 'dart':
href = 'http://angular-examples.github.io/' + example;
break;
case 'api':
href = '/resources/api-live-examples/' + example + '/' + plnkr + '.html';
}
return href;
}

function span(text) { return '<span>' + text + '</span>'; }

return {
restrict: 'E',
scope: true,
Expand All @@ -47,35 +85,41 @@ angularIO.directive('liveExample', ['$location', function ($location) {
var ex = attrs.name || NgIoUtil.getExampleName($location);
var embedded = attrs.hasOwnProperty('embedded');
var plnkr = embedded ? 'eplnkr' : 'plnkr';
var href, template;
var href, template, exLang;
var imageBase = '/resources/images/';
var defaultImg = 'plunker/placeholder.png';

var noImg = angular.isDefined(attrs.noimg);
var isApi = !!attrs.api;
console.log(noImg);
if (attrs.plnkr) {
plnkr = attrs.plnkr + '.' + plnkr;
}

if (isApi) {
ex = attrs.api;
exLang = 'api';
} else {
exLang = isForDart ? 'dart' : isForJs ? 'js' : 'ts';
}

var isForDart = attrs.lang === 'dart' || NgIoUtil.isDoc($location, 'dart');
var isForJs = attrs.lang === 'js' || NgIoUtil.isDoc($location, 'js');
var exLang = isForDart ? 'dart' : isForJs ? 'js' : 'ts';

if (embedded && !isForDart) {
href = '/resources/live-examples/' + ex + '/' + exLang + '/' + plnkr + '.html';
href = getHref(exLang, ex, plnkr);
img = imageBase + (attrs.img || defaultImg);
template = embeddedTemplate(href, img);
template = noImg ? embeddedNoImgTemplate(href) : embeddedTemplate(href, img);
} else {
var href = isForDart
? 'http://angular-examples.github.io/' + ex
: '/resources/live-examples/' + ex + '/' + exLang + '/' + plnkr + '.html'
href = getHref(exLang, ex, plnkr);

// Link to live example.
var template = a(text, { href: href, target: '_blank' });
template = a(text, { href: href, target: '_blank' });

// The hosted example and sources are in different locations for Dart.
// Also show link to sources for Dart, unless noSource is specified.
if (isForDart && !attrs.hasOwnProperty('nosource')) {
var srcText = attrs.srcText || 'view source';
var srcHref = 'http://github.com/angular-examples/' + ex;
href = getHref('dart', ex);
template = span(template + ' (' + a(srcText, { href: srcHref, target: '_blank' }) + ')');
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,4 @@ module.exports = function(encodeCodeBlock) {
return str;
};

};
};
4 changes: 3 additions & 1 deletion tools/api-builder/links-package/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ module.exports = new Package('links', [])
.factory(require('./inline-tag-defs/linkDocs'))
.factory(require('./inline-tag-defs/example'))
.factory(require('./inline-tag-defs/exampleTabs'))
.factory(require('./inline-tag-defs/liveExample'))
.factory(require('dgeni-packages/links/services/getAliases'))
.factory(require('dgeni-packages/links/services/getDocFromAlias'))
.factory(require('./services/getLinkInfo'))
Expand All @@ -14,11 +15,12 @@ module.exports = new Package('links', [])
.factory(require('./services/deprecatedDocsLinkDisambiguator'))
.factory(require('./services/getApiFragmentFileName'))

.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) {
.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef, liveExampleInlineTagDef) {
inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
inlineTagProcessor.inlineTagDefinitions.push(linkDocsInlineTagDef);
inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef);
inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef);
inlineTagProcessor.inlineTagDefinitions.push(liveExampleInlineTagDef);
})

.config(function(getLinkInfo, moduleScopeLinkDisambiguator, deprecatedDocsLinkDisambiguator) {
Expand Down
39 changes: 39 additions & 0 deletions tools/api-builder/links-package/inline-tag-defs/liveExample.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
var path = require('canonical-path');
var fs = require("fs");

/**
* @dgService liveExampleInlineTagDef
* @description
* Process inline liveExample tags (of the form {@liveExample demo-path embedded }),
* replacing them with a <live-example> directive.
* Examples:
* {@liveExample core/animation/ts/dsl }
* {@liveExample core/di/ts/contentChildren embedded }
* @kind function
*/
module.exports = function liveExampleInlineTagDef(getLinkInfo, parseArgString, getApiFragmentFileName, createDocMessage, log) {
return {
name: 'liveExample',
description: 'Process inline liveExample tags (of the form {@liveExample demo-path embedded }), replacing them with <live-example>',
handler: function(doc, tagName, tagDescription) {

var tagArgs = parseArgString(tagDescription);
var unnamedArgs = tagArgs._;
var relativePath = unnamedArgs[0] !== 'embedded' ? unnamedArgs[0] : unnamedArgs[1];
var embedded = unnamedArgs.indexOf('embedded') >= 0 ? 'embedded' : '';
var imgPath = tagArgs.img;

// check if fragment file actually exists.
var apiPlunkerFile = getApiPlunkerFile(relativePath);
if ( !fs.existsSync(apiPlunkerFile)) {
log.warn(createDocMessage(`Invalid example (unable to locate plunker file: ${apiPlunkerFile}`));
}

return [ `<live-example api="${relativePath}" ${embedded} ${imgPath ? `img="${imgPath}"` : 'noimg'}></live-example>` ];
}
};
};

function getApiPlunkerFile(relativePath) {
return path.join('/resources/api-live-examples', `${relativePath}/plnkr.html`);
}
30 changes: 30 additions & 0 deletions tools/plunker-builder/boilerplate/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Animations</title>
<meta name="viewport" content="width=device-width, initial-scale=1">

<!-- Polyfill for Web Animations -->
<script src="https://unpkg.com/[email protected]"></script>

<!-- Polyfill(s) for older browsers -->
<script src="https://unpkg.com/core-js/client/shim.min.js"></script>

<script src="https://unpkg.com/[email protected]?main=browser"></script>
<script src="https://unpkg.com/[email protected]"></script>
<script src="https://unpkg.com/[email protected]/dist/system.src.js"></script>

<script src="systemjs.config.js"></script>
<script>
System.import('app').catch(function(err){ console.error(err); });
</script>
</head>

<body>
<example-app>
Loading...
</example-app>
</body>

</html>
5 changes: 5 additions & 0 deletions tools/plunker-builder/boilerplate/main.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './module.ts';

platformBrowserDynamic().bootstrapModule(AppModule);
Loading

0 comments on commit aa9560d

Please sign in to comment.