From b48cde3a4387197f8990e81bfe411d33e8c784e4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 2 Jun 2016 09:06:03 -0700 Subject: [PATCH] chore(_util-fns): generalize makeExample, drop makeProjExample (#1510) + Rename adjustExample{Path|Title} to adjustTsExample*4Dart + `makeExample` can now work with both doc folder relative and project relative paths. --- public/_includes/_util-fns.jade | 96 ++++++++++++------- public/docs/dart/latest/_util-fns.jade | 8 +- .../latest/guide/server-communication.jade | 2 +- public/docs/ts/latest/quickstart.jade | 6 +- 4 files changed, 68 insertions(+), 44 deletions(-) diff --git a/public/_includes/_util-fns.jade b/public/_includes/_util-fns.jade index f9ad971b95..b46a6c8c06 100644 --- a/public/_includes/_util-fns.jade +++ b/public/_includes/_util-fns.jade @@ -53,10 +53,10 @@ mixin ifDocsFor(langPattern) block //- Use to map inlined (prose) TS paths into, say, Dart paths via the -//- adjustExamplePath transformer function. +//- adjustTsExamplePathForDart transformer function. mixin adjExPath(path) - if adjustExamplePath - | #{adjustExamplePath(path)} + if adjustTsExamplePathForDart + | #{adjustTsExamplePathForDart(path)} else | #{path} @@ -65,8 +65,9 @@ mixin includeShared(filePath, region) !=partial(newPath) mixin makeExample(_filePath, region, _title, stylePatterns) - - var filePath = adjustExamplePath ? adjustExamplePath(_filePath) : _filePath; - - var title = adjustExampleTitle ? adjustExampleTitle(_title) : _title; + - var adjustments = adjustExamplePathAndTitle({filePath:_filePath, title:_title}); + - var filePath = adjustments.filePath; + - var title = adjustments.title; - var language = attributes.language || getExtn(filePath); - var frag = getFrag(filePath, region); - var defaultFormat = frag.split('\n').length > 2 ? "linenums" : ""; @@ -82,35 +83,21 @@ mixin makeExample(_filePath, region, _title, stylePatterns) code-example(language="#{language}" format="#{format}") != styleString(frag, stylePatterns) -//- 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 + ')'; +//- Like makeExample, but: (1) doesn't show line numbers. (2) If region +//- is omitted and title is 'foo (r)' then region is taken as 'r'. +//- (3) Title will always end with a phrase in parentheses; if no such +//- ending is given or is just (), then the title will be suffixed with +//- either "(excerpt)", or "(#{_region})" when _region is defined. +mixin makeExcerpt(_filePath, _region, _title, stylePatterns) + - var matches = _filePath.match(/(.*)\s+\(([\w ]*)\)$/); + - var parenText; + - if (matches) { _filePath = matches[1]; parenText = matches[2]; } + - var adjustments = adjustExamplePathAndTitle({filePath:_filePath, title:_title}); + - var filePath = adjustments.filePath; + - var title = adjustments.title; + - var region = _region || parenText; + - var excerpt = !region || parenText === '' ? 'excerpt' : region; + - if (title) title = title + ' (' + excerpt + ')'; +makeExample(filePath, region, title, stylePatterns)(format='.') //- Extract the doc example name from `current`. @@ -121,10 +108,10 @@ mixin makeExcerpt(projRootRelativePath, region, title, stylePatterns) mixin makeTabs(filePaths, regions, tabNames, stylePatterns) - filePaths = strSplit(filePaths); - - if (adjustExamplePath) filePaths = filePaths.map(adjustExamplePath); + - if (adjustTsExamplePathForDart) filePaths = filePaths.map(adjustTsExamplePathForDart); - regions = strSplit(regions, filePaths.length); - tabNames = strSplit(tabNames, filePaths.length); - - if (adjustExampleTitle) tabNames = tabNames.map(adjustExampleTitle); + - if (adjustTsExampleTitleForDart) tabNames = tabNames.map(adjustTsExampleTitleForDart); code-tabs each filePath,index in filePaths @@ -216,6 +203,43 @@ script. return CCSstyle[style] = value } //--------------------------------------------------------------------------------------------------------- +//- Converts the given project-relative path (like 'app/main.ts') +//- to a doc folder relative path (like 'quickstart/ts/app/main.ts') +//- by prefixing it with '/ts/'. If title is not given, +//- then the project-relative path is used, adjusted to remove numeric +//- file version qualifiers; e.g. 'styles.1.css' becomes 'styles.css'. +- var adjExampleProjPathAndTitle = function(ex/*:{filePath,title}*/) { +- // E.g. of a project relative path is 'app/main.ts' +- if (ex.title === null || ex.title === undefined) { +- // Title is not given so take it to be ex.filePath. +- // Is title like styles.1.css? Then drop the '.1' qualifier: +- var matches = ex.filePath.match(/^(.*)\.\d(\.\w+)$/); +- ex.title = matches ? matches[1] + matches[2] : ex.filePath; +- } +- ex.filePath = getExampleName() + '/' + _docsFor + '/' + ex.filePath; +- return ex; +- }; + +//- If the given path is project relative, then first convert it using +//- adjExampleProjPathAndTitle(ex). Then the path is adjusted to match +//- the documentation language. +- var adjustExamplePathAndTitle = function(ex/*:{filePath,title}*/) { +- // Not a doc folder relative path? Assume that it is app project relative. +- if(isProjRelDir(ex.filePath)) adjExampleProjPathAndTitle(ex); +- // Adjust doc folder relative paths if adjustment functions exist. +- if(adjustTsExamplePathForDart) ex.filePath = adjustTsExamplePathForDart(ex.filePath); +- if(adjustTsExampleTitleForDart) ex.title = adjustTsExampleTitleForDart(ex.title); +- return ex; +- }; + +//- Returns truthy iff path is example project relative. +- var isProjRelDir = function(path) { +- return !path.match(/\/(js|ts|dart)(-snippets)?\//) && !path.endsWith('e2e-spec.js'); +- // Last conjunct handles case for shared project e2e test file like +- // cb-component-communication/e2e-spec.js (is shared between ts & dart) +- // TODO: generalize: compare start with getExampleName(); which needs to be fixed. +- }; + - var translatePath = function(filePath, region) { - filePath = filePath.trim(); - var regionPad = (region && region.length) ? '-' + region.toString() : ''; diff --git a/public/docs/dart/latest/_util-fns.jade b/public/docs/dart/latest/_util-fns.jade index 9bd0289b4a..5d54cf117d 100644 --- a/public/docs/dart/latest/_util-fns.jade +++ b/public/docs/dart/latest/_util-fns.jade @@ -32,7 +32,7 @@ mixin liveExampleLink2(linkText, exampleUrlPartName) - var href = 'http://github.com/angular-examples/' + ex; span #[+liveExampleLink(linkText, ex)] (#[a(href='#{href}' target="_blank") #{srcText}]) -- var adjustExamplePath = function(_path) { +- var adjustTsExamplePathForDart = function(_path) { - if(!_path) return _path; - var path = _path.trim(); - var folder = getFolder(path); @@ -52,15 +52,15 @@ mixin liveExampleLink2(linkText, exampleUrlPartName) - return (folder ? folder + '/' : '') + baseNameNoExt + (extn ? '.' + extn : ''); - }; -- var adjustExampleTitle = function(_title) { -- if(!_title || !adjustExamplePath) return _title; +- var adjustTsExampleTitleForDart = function(_title) { +- if(!_title || !adjustTsExamplePathForDart) return _title; - var title = _title.trim(); - // Assume title is a path if it ends with an extension like '.foo', - // optionally followed by some comment in parentheses. - var matches = title.match(/(.*\.\w+)($|\s*\([\w ]+\)$)/); - if(matches && matches.length == 3) { - // e.g. matches == ['abc.ts (excerpt)', 'abc.ts', ' (excerpt)'] -- var path = adjustExamplePath(matches[1]); +- var path = adjustTsExamplePathForDart(matches[1]); - title = path + matches[2]; - } - return title; diff --git a/public/docs/dart/latest/guide/server-communication.jade b/public/docs/dart/latest/guide/server-communication.jade index 51bd3a63db..116790bcfa 100644 --- a/public/docs/dart/latest/guide/server-communication.jade +++ b/public/docs/dart/latest/guide/server-communication.jade @@ -35,7 +35,7 @@ block http-providers [ng2dtri]: https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer#resolved_identifiers - var stylePattern = { pnk: /(resolved_identifiers:|Browser.*)/gm, otl: /(- angular2:)|(transformers:)/g }; - +makeExcerpt('pubspec.yaml', 'transformers', 'pubspec.yaml (transformers)', stylePattern) + +makeExcerpt('pubspec.yaml', 'transformers', null, stylePattern) block getheroes-and-addhero :marked diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index a77ae3a0b3..635944ef27 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -211,7 +211,7 @@ p. #[b Create the component file] #[code #[+adjExPath('app/app.component.ts')]] (in this newly created directory) with the following content: -+makeProjExample('app/app.component.ts') ++makeExample('app/app.component.ts') .l-verbose-section :marked @@ -300,7 +300,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: -+makeProjExample('app/main.ts') ++makeExample('app/main.ts') .l-verbose-section :marked @@ -345,7 +345,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: -+makeProjExample('index.html') ++makeExample('index.html') .l-verbose-section :marked