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

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
@@ -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');
       }
     });
 

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);
 });

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 + "'";
 }
-
-

tools/api-builder/links-package/inline-tag-defs/linkDevGuide.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 ?
+        '<a href="' + url + '">' + title + '</a>' :
+        '<span>' + title + '</span>';
+    }
+  };
+  return _self;
+};