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.

Author: chalin

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
@@ -1028,7 +1030,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) {
@@ -1038,7 +1040,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');
       }
     });
 

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 "<a href='" + url + "'>" + title + "</a>";
-
+      return isValid ?
+        '<a href="' + url + '">' + title + '</a>' :
+        '<span>' + title + '</span>';
     }
   };
+  return _self;
 };
-