chore(api-builder): support API doc language agnostic URIs

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

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