From d9343067fb2488c5925345e422c0053096a29113 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 7 Jul 2016 21:35:40 -0700 Subject: [PATCH 1/3] chore(api-builder): 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. --- tools/api-builder/links-package/index.js | 6 +++--- .../inline-tag-defs/{linkDevGuide.js => linkDocs.js} | 0 2 files changed, 3 insertions(+), 3 deletions(-) rename tools/api-builder/links-package/inline-tag-defs/{linkDevGuide.js => linkDocs.js} (100%) 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/linkDevGuide.js b/tools/api-builder/links-package/inline-tag-defs/linkDocs.js similarity index 100% rename from tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js rename to tools/api-builder/links-package/inline-tag-defs/linkDocs.js From 010b845ca7b4f97addf27447812a7f40e749bff1 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 7 Jul 2016 21:43:10 -0700 Subject: [PATCH 2/3] chore(api-builder): 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. --- gulpfile.js | 10 +++- .../links-package/inline-tag-defs/linkDocs.js | 58 +++++++++++++------ 2 files changed, 47 insertions(+), 21 deletions(-) diff --git a/gulpfile.js b/gulpfile.js index dc10189b26..3794ea5c06 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 @@ -1036,7 +1038,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) { @@ -1046,7 +1048,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/inline-tag-defs/linkDocs.js b/tools/api-builder/links-package/inline-tag-defs/linkDocs.js index 1e40227e81..6254fc2d2f 100644 --- a/tools/api-builder/links-package/inline-tag-defs/linkDocs.js +++ b/tools/api-builder/links-package/inline-tag-defs/linkDocs.js @@ -2,38 +2,59 @@ var path = require('canonical-path'); var fs = require("fs"); var jsonFile = require('jsonfile'); -var INLINE_LINK = /(\S+)(?:\s+([\s\S]+))?/; - /** - * @dgService linkDevGuideInlineTagDef + * @dgService linkDocsInlineTagDef * @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 ). + * 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 - * {@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" } + * {@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 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) { +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 DevGuide example (unable to locate jade file: "' + jadePath + '")', doc)); + 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)) { @@ -42,12 +63,13 @@ module.exports = function linkDevGuideInlineTagDef(parseArgString, createDocMess } } } - var url = path.join('/docs', uri + '.html'); + var url = path.join('/docs', uri + '.html' + paramAnchor); title = title || key || url; - return "" + title + ""; - + return isValid ? + '' + title + '' : + '' + title + ''; } }; + return _self; }; - From cd099b5c5ed442cc8badd89d19150ebc85ebddb4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 7 Jul 2016 21:43:54 -0700 Subject: [PATCH 3/3] chore(api-builder): minor code cleanup --- .../links-package/inline-tag-defs/example.js | 10 ---------- 1 file changed, 10 deletions(-) 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 + "'"; } - -