From 4da23bfe578e5aa208bd6a438ebc5e74d5b2816f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 7 Jul 2016 21:35:40 -0700 Subject: [PATCH] chore(api-builder): linkDevGuide -> linkDocs;linkDocs can default the lang closes #1849 1) Rename linkDevGuide to linkDocs Rename the specialized API docs `@linkDevGuide` tag to `@linkDocs` since it is meant to be used to refer to all angular.io docs, not just the developer guide. 2) let linkDocs links resolve to proper language The old linkDevGuide required URIs to be given in the form 'ts/latest/guide/architecture' which forced all language versions of the API pages to refer to the ts versions of the doc pages they linked to. This PR fixes that problem. URIs are now given in the form 'guide/architecture' and then rendered properly for each language. Of course, when needed, it is still possible to give a language specific URI. chore(api-builder): minor code cleanup --- gulpfile.js | 10 ++- tools/api-builder/links-package/index.js | 6 +- .../links-package/inline-tag-defs/example.js | 10 --- .../inline-tag-defs/linkDevGuide.js | 53 ------------- .../links-package/inline-tag-defs/linkDocs.js | 75 +++++++++++++++++++ 5 files changed, 85 insertions(+), 69 deletions(-) delete mode 100644 tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js create mode 100644 tools/api-builder/links-package/inline-tag-defs/linkDocs.js diff --git a/gulpfile.js b/gulpfile.js index 70a02b70be..6f784956fb 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -403,7 +403,9 @@ gulp.task('add-example-boilerplate', function() { // copies boilerplate files to locations // where an example app is found -gulp.task('_copy-example-boilerplate', copyExampleBoilerplate); +gulp.task('_copy-example-boilerplate', function () { + if (!argv.fast) copyExampleBoilerplate(); +}); // copies boilerplate files to locations @@ -1066,7 +1068,7 @@ function buildApiDocs(targetLanguage) { try { // Build a specialized package to generate different versions of the API docs var package = new Package('apiDocs', [require(path.resolve(TOOLS_PATH, 'api-builder/angular.io-package'))]); - package.config(function(log, targetEnvironments, writeFilesProcessor, readTypeScriptModules) { + package.config(function(log, targetEnvironments, writeFilesProcessor, readTypeScriptModules, linkDocsInlineTagDef) { log.level = _dgeniLogLevel; ALLOWED_LANGUAGES.forEach(function(target) { targetEnvironments.addAllowed(target); }); if (targetLanguage) { @@ -1076,7 +1078,9 @@ function buildApiDocs(targetLanguage) { // Don't read TypeScript modules if we are not generating API docs - Dart I am looking at you! readTypeScriptModules.$enabled = false; } - writeFilesProcessor.outputFolder = targetLanguage + '/latest/api'; + linkDocsInlineTagDef.lang = targetLanguage; + linkDocsInlineTagDef.vers = 'latest'; + writeFilesProcessor.outputFolder = path.join(targetLanguage, linkDocsInlineTagDef.vers, 'api'); } }); diff --git a/tools/api-builder/links-package/index.js b/tools/api-builder/links-package/index.js index 3036c2441b..5391399055 100644 --- a/tools/api-builder/links-package/index.js +++ b/tools/api-builder/links-package/index.js @@ -3,7 +3,7 @@ var Package = require('dgeni').Package; module.exports = new Package('links', []) .factory(require('./inline-tag-defs/link')) -.factory(require('./inline-tag-defs/linkDevGuide')) +.factory(require('./inline-tag-defs/linkDocs')) .factory(require('./inline-tag-defs/example')) .factory(require('./inline-tag-defs/exampleTabs')) .factory(require('dgeni-packages/links/services/getAliases')) @@ -12,9 +12,9 @@ module.exports = new Package('links', []) .factory(require('./services/parseArgString')) .factory(require('./services/getApiFragmentFileName')) -.config(function(inlineTagProcessor, linkInlineTagDef, linkDevGuideInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) { +.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) { inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef); - inlineTagProcessor.inlineTagDefinitions.push(linkDevGuideInlineTagDef); + inlineTagProcessor.inlineTagDefinitions.push(linkDocsInlineTagDef); inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef); inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef); }); diff --git a/tools/api-builder/links-package/inline-tag-defs/example.js b/tools/api-builder/links-package/inline-tag-defs/example.js index caaccfd61f..1df3f0223f 100644 --- a/tools/api-builder/links-package/inline-tag-defs/example.js +++ b/tools/api-builder/links-package/inline-tag-defs/example.js @@ -40,18 +40,8 @@ module.exports = function exampleInlineTagDef(getLinkInfo, parseArgString, getAp }; }; -// Examples of what @example and @exampleTabs markup looks like in the angular/angular source. -//* -//* {@example core/application_spec.ts hello-app -title='Sample component' } -//* -//* {@exampleTabs core/application_spec.ts,core/application_spec.ts "hello-app,hello-app2" -titles="Hello app1, Hello app2" } -//* - - function quote(str) { if (str == null || str.length === 0) return str; str = str.replace("'","'\'"); return "'" + str + "'"; } - - diff --git a/tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js b/tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js deleted file mode 100644 index 1e40227e81..0000000000 --- a/tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js +++ /dev/null @@ -1,53 +0,0 @@ -var path = require('canonical-path'); -var fs = require("fs"); -var jsonFile = require('jsonfile'); - -var INLINE_LINK = /(\S+)(?:\s+([\s\S]+))?/; - -/** - * @dgService linkDevGuideInlineTagDef - * @description - * Process inline link tags (of the form {@linkDevGuide some/uri 'Some Title'}), replacing them with HTML anchors. - * The uri should point to a jade page in the DevGuide without the .jade extension ( under public/docs ). - * If the title is omitted an attempt will be made to determine the title of the jade page being pointed to. If not found - * the the title will simply be the last part of the link. - * Examples - * {@linkDevGuide ts/latest/guide/gettingStarted } - * {@linkDevGuide js/latest/guide/gettingStarted 'Javascript version of getting started' } - * {@linkDevGuide ts/latest/guide/gettingStarted title="Typescript version of getting started" } - * @kind function - */ -module.exports = function linkDevGuideInlineTagDef(parseArgString, createDocMessage, log) { - return { - name: 'linkDevGuide', - description: 'Process inline link tags (of the form {@link some/uri "Some Title"}), replacing them with HTML anchors', - handler: function(doc, tagName, tagDescription) { - - // Parse out the uri and title - var tagArgs = parseArgString(tagDescription); - var unnamedArgs = tagArgs._; - var uri = unnamedArgs[0]; - var title = tagArgs.title || (unnamedArgs.length > 1 ? unnamedArgs[1] : null); - - var jadePath = path.join('./public/docs', uri + '.jade'); - var key = path.basename(jadePath, '.jade'); - if ( !fs.existsSync(jadePath)) { - log.warn(createDocMessage('Invalid DevGuide example (unable to locate jade file: "' + jadePath + '")', doc)); - } else { - if (!title) { - var jsonFilePath = path.join(path.dirname(jadePath), '_data.json'); - if ( fs.existsSync(jsonFilePath)) { - var jsonObj = jsonFile.readFileSync(jsonFilePath); - title = jsonObj[key] && jsonObj[key].title; - } - } - } - var url = path.join('/docs', uri + '.html'); - title = title || key || url; - - return "" + title + ""; - - } - }; -}; - diff --git a/tools/api-builder/links-package/inline-tag-defs/linkDocs.js b/tools/api-builder/links-package/inline-tag-defs/linkDocs.js new file mode 100644 index 0000000000..6254fc2d2f --- /dev/null +++ b/tools/api-builder/links-package/inline-tag-defs/linkDocs.js @@ -0,0 +1,75 @@ +var path = require('canonical-path'); +var fs = require("fs"); +var jsonFile = require('jsonfile'); + +/** + * @dgService linkDocsInlineTagDef + * @description + * Process inline link tags (of the form {@linkDocs some/uri 'Some Title'}), replacing them with HTML anchors. + * The uri should point to a jade page in the Docs without the .jade extension ( under public/docs ). + * If the title is omitted an attempt will be made to determine the title of the jade page being pointed to. If not found + * the the title will simply be the last part of the link. + * Examples + * {@linkDocs guide/gettingStarted 'QuickStart'} + * {@linkDocs ts/latest/guide/quickstart } + * {@linkDocs js/latest/guide/quickstart 'Javascript version of getting started' } + * {@linkDocs ts/latest/guide/quickstart title="Typescript version of getting started" } + * @kind function + * @property {string} lang Default docs API page language when not explicitly given in URI; one of ts|js|dart. + * @property {string} vers Default docs version. Currently only 'latest'. + */ +module.exports = function linkDocsInlineTagDef(parseArgString, createDocMessage, log) { + var _self = { + name: 'linkDocs', + lang: 'ts', + vers: 'latest', + description: 'Process inline link tags (of the form {@linkDocs some/uri [title=]"Some Title"}), replacing them with HTML anchors', + + handler: function(doc, tagName, tagDescription) { + // Parse out the uri and title + var tagArgs = parseArgString(tagDescription); + var unnamedArgs = tagArgs._; + var uri = unnamedArgs[0]; + var title = tagArgs.title || (unnamedArgs.length > 1 ? unnamedArgs[1] : null); + + // Are there parameters and/or an anchor? + var matches, paramAnchor = ''; + if (matches = uri.match(/([^\#\?]*)([\#\?].*)/)) { + uri = matches[1]; + paramAnchor = matches[2]; + } + + // Is this a chapter-relative uri like 'guide/...'? + if (!uri.match(/^(ts|js|dart)/)) { + var lang = _self.lang; + var vers = _self.vers; + var prevUri = uri; + uri = path.join(lang, vers, uri); + log.info('Ajusted linkDocs chapter-relative uri (' + doc.fileInfo.baseName + '): ' + prevUri + ' -> ' + uri); + } + + var isValid = false; + var jadePath = path.join('./public/docs', uri + '.jade'); + var key = path.basename(jadePath, '.jade'); + if ( !fs.existsSync(jadePath)) { + log.warn(createDocMessage('Invalid docs link (unable to locate jade file: "' + jadePath + '")', doc)); + } else { + isValid = true; + if (!title) { + var jsonFilePath = path.join(path.dirname(jadePath), '_data.json'); + if ( fs.existsSync(jsonFilePath)) { + var jsonObj = jsonFile.readFileSync(jsonFilePath); + title = jsonObj[key] && jsonObj[key].title; + } + } + } + var url = path.join('/docs', uri + '.html' + paramAnchor); + title = title || key || url; + + return isValid ? + '' + title + '' : + '' + title + ''; + } + }; + return _self; +};