From 5b1a84be4cb18a080c390622c46ce04e567a7448 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 18 May 2016 10:27:51 -0700 Subject: [PATCH] chore(docs): revise makeExcerpt mixin, add makeProjExample mixin Be more DRY when referencing examples and excerpts. E.g., ```jade +makeExcerpt('quickstart/ts/app/app.component.ts', 'import', 'app/app.component.ts (import)') ``` can now be just ```jade +makeExcerpt('app/app.component.ts', 'import') ``` Defined new mixin for examples named `makeProjExample` using this new scheme. The original `makeExample` has been left untouched. Applied new mixins to quickstart. closes #1420 --- public/_includes/_util-fns.jade | 44 ++++++++++++++++--- .../docs/_examples/quickstart/ts/app/main.ts | 4 +- public/docs/ts/latest/quickstart.jade | 18 ++++---- 3 files changed, 48 insertions(+), 18 deletions(-) diff --git a/public/_includes/_util-fns.jade b/public/_includes/_util-fns.jade index 1786e7fd8a..592068484d 100644 --- a/public/_includes/_util-fns.jade +++ b/public/_includes/_util-fns.jade @@ -68,13 +68,43 @@ mixin makeExample(_filePath, region, _title, stylePatterns) .example-title #{title} code-example(language="#{language}" format="#{format}") != styleString(frag, stylePatterns) - -//- Like makeExample, but doesn't show line numbers and -//- title is appened with `(excerpt)` if it doesn't already -//- end with a parenthetical remark. -mixin makeExcerpt(_filePath, region, _title, stylePatterns) - - if (_title && !_title.match(/\([\w ]+\)$/)) _title = _title + ' (excerpt)'; - +makeExample(_filePath, region, _title, stylePatterns)(format='.') + +//- Like makeExample, but the first argument is a path that is +//- relative to the project root. Unless title is defined, +//- the project relative path will be used. +mixin makeProjExample(projRootRelativePath, region, title, stylePatterns) + - var relPath = projRootRelativePath.trim(); + - var filePath = getExampleName() + '/ts/' + relPath; + - if (!title) { + - // Is path like styles.1.css? Then drop the '.1' qualifier: + - var matches = relPath.match(/^(.*)\.\d(\.\w+)$/); + - title = matches ? matches[1] + matches[2] : relPath; + - } + +makeExample(filePath, region, title, stylePatterns) + +//- Like makeExample, but doesn't show line numbers, and the first +//- argument is a path that is relative to the example project root. +//- Unless title is defined, the project relative path will be used. +//- Title will always end with a phrase in parentheses; if no such +//- ending is given, then the title will be suffixed with +//- either "(excerpt)", or "(#{region})" when region is defined. +mixin makeExcerpt(projRootRelativePath, region, title, stylePatterns) + - var relPath = projRootRelativePath.trim(); + - var filePath = getExampleName() + '/ts/' + relPath; + - if (!title) { + - // Is path like styles.1.css? Then drop the '.1' qualifier: + - var matches = relPath.match(/^(.*)\.\d(\.\w+)$/); + - title = matches ? matches[1] + matches[2] : relPath; + - } + - var excerpt = region || 'excerpt'; + - if (title && !title.match(/\([\w ]+\)$/)) title = title + ' (' + excerpt + ')'; + +makeExample(filePath, region, title, stylePatterns)(format='.') + +//- Extract the doc example name from `current`. +- var getExampleName = function() { +- var dir = current.path[current.path.length - 1]; +- return dir == 'latest' ? current.source : dir; +- }; mixin makeTabs(filePaths, regions, tabNames, stylePatterns) - filePaths = strSplit(filePaths); diff --git a/public/docs/_examples/quickstart/ts/app/main.ts b/public/docs/_examples/quickstart/ts/app/main.ts index 433fd05c80..2aede345e9 100644 --- a/public/docs/_examples/quickstart/ts/app/main.ts +++ b/public/docs/_examples/quickstart/ts/app/main.ts @@ -1,8 +1,8 @@ // #docregion import { bootstrap } from '@angular/platform-browser-dynamic'; -// #docregion app-component +// #docregion import import { AppComponent } from './app.component'; -// #enddocregion app-component +// #enddocregion import bootstrap(AppComponent); diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 526986a627..fb5bd5e910 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -208,7 +208,7 @@ p. #[b Create the component file] #[code #[+adjExPath('app/app.component.ts')]] (in this newly created directory) with the following content: -+makeExample('quickstart/ts/app/app.component.ts', '', 'app/app.component.ts')(format='.') ++makeProjExample('app/app.component.ts') .l-verbose-section :marked @@ -241,7 +241,7 @@ p. Here we import the Angular 2 core so that our component code can have access to the `@Component` #{_decorator}. - +makeExcerpt('quickstart/ts/app/app.component.ts', 'import', 'app/app.component.ts (import)') + +makeExcerpt('app/app.component.ts', 'import') h3#component-decorator @Component #{_decorator} +ifDocsFor('ts') @@ -254,7 +254,7 @@ p. component class. The metadata tells Angular how to create and use this component. - +makeExcerpt('quickstart/ts/app/app.component.ts', 'metadata', 'app/app.component.ts (metadata)')(format='.') + +makeExcerpt('app/app.component.ts', 'metadata') block annotation-fields :marked @@ -279,7 +279,7 @@ p. :marked ### Component class At the bottom of the file is an empty, do-nothing class named `AppComponent`. - +makeExcerpt('quickstart/ts/app/app.component.ts', 'class', 'app/app.component.ts (class)') + +makeExcerpt('app/app.component.ts', 'class') :marked When we're ready to build a substantive application, we can expand this class with properties and application logic. @@ -297,7 +297,7 @@ block create-main Now we need something to tell Angular to load the root component. Create the file #[code #[+adjExPath('app/main.ts')]] with the following content: -+makeExample('quickstart/ts/app/main.ts', '', 'app/main.ts')(format='.') ++makeProjExample('app/main.ts') .l-verbose-section :marked @@ -342,7 +342,7 @@ h2#index Step 4: Add #[code index.html] In the *#{_indexHtmlDir}* folder create an `index.html` file and paste the following lines into it: -+makeExample('quickstart/ts/index.html', '', 'index.html')(format='.') ++makeProjExample('index.html') .l-verbose-section :marked @@ -360,7 +360,7 @@ h2#index Step 4: Add #[code index.html] :marked ### Libraries We loaded the following scripts - +makeExcerpt('quickstart/ts/index.html', 'libraries', 'index.html') + +makeExcerpt('index.html', 'libraries') :marked We begin with es6-shim which monkey patches the global context (window) with essential features of ES2015 (ES6). Next are the polyfills for Angular2, `zone.js` and `reflect-metadata`. @@ -407,7 +407,7 @@ h2#index Step 4: Add #[code index.html] Our QuickStart makes such requests when one of its application TypeScript files has an import statement like this: - +makeExcerpt('quickstart/ts/app/main.ts', 'app-component', 'main.ts (excerpt)') + +makeExcerpt('app/main.ts', 'import') :marked Notice that the module name (after `from`) does not mention a filename extension. In the configuration we tell SystemJS to default the extension to `js`, a JavaScript file. @@ -463,7 +463,7 @@ h2#index Step 4: Add #[code index.html] Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, perhaps with the minimal styles shown below. For the full set of master styles used by the documentation samples, see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css). -+makeExcerpt('quickstart/ts/styles.1.css', '', 'styles.css') ++makeExcerpt('styles.1.css') .l-main-section h2#build-and-run Step 5: Build and run the app!