chore: Dart API doc gen cleanup and refactoring (#2641)

- gulp task: don’t copy over internal libraries.
- Adjust anchor hrefs rather than use `<base href>` in generated API
pages. The net effect is the same.

Author: chalin

gulpfile.js

@@ -1381,14 +1381,14 @@ function buildApiDocsForDart() {
   dabInfo.ngDartDocPath = path.join(ngPathFor('dart'), relDartDocApiDir);
   // Exclude API entries for developer/internal libraries. Also exclude entries for
   // the top-level catch all "angular2" library (otherwise every entry appears twice).
-  dabInfo.excludeLibRegExp = new RegExp(/^(?!angular2)|\.testing|_|codegen|^angular2$/);
+  dabInfo.excludeLibRegExp = new RegExp(/^(?!angular2)|testing|_|codegen|^angular2$/);
 
   try {
     checkAngularProjectPath(ngPathFor('dart'));
     var destPath = dabInfo.ngIoDartApiDocPath;
     var sourceDirs = fs.readdirSync(dabInfo.ngDartDocPath)
-      .filter((name) => !name.match(/^index/))
-      .map((name) => path.join(dabInfo.ngDartDocPath, name));
+      .filter(name => !name.match(/^index|^(?!angular2)|testing|codegen/))
+      .map(name => path.join(dabInfo.ngDartDocPath, name));
     log.info(`Building Dart API pages for ${sourceDirs.length} libraries`);
 
     return copyFiles(sourceDirs, [destPath]).then(() => {
@@ -1398,7 +1398,6 @@ function buildApiDocsForDart() {
       const tmpDocsPath = path.resolve(path.join(process.env.HOME, 'tmp/docs.json'));
       if (argv.dumpDocsJson) fs.writeFileSync(tmpDocsPath, JSON.stringify(apiEntries, null, 2));
       dab.createApiDataAndJadeFiles(apiEntries);
-
     }).catch((err) => {
       console.error(err);
     });

tools/dart-api-builder/dab.js

@@ -135,7 +135,7 @@ module.exports = function dabFactory(ngIoProjPath) {
         assert(depth === 1 || depth == 2, 'depth ' + depth);
         const jadeFilePath = path.resolve(outFileNoExtn + '.jade');
         const breadcrumbs = $('header > nav ol.breadcrumbs');
-        fs.writeFileSync(jadeFilePath, apiEntryJadeTemplate(depth, breadcrumbs, div));
+        fs.writeFileSync(jadeFilePath, apiEntryJadeTemplate($, depth, breadcrumbs, div));
         // In case harp cached the .html version, remove it since it will be generated.
         try {
             fs.unlinkSync(path.resolve(outFileNoExtn + '.html'));
@@ -197,17 +197,29 @@ module.exports = function dabFactory(ngIoProjPath) {
     return _self;
 };
 
+function _adjustAnchorHref($, $elt, hrefPathPrefix) {
+  if (!hrefPathPrefix) return;
+  $elt.find('a[href]').each((i, e) => {
+    let href = $(e).attr('href')
+    // Do nothing to absolute or external links
+    if (href.match(/^\/|^[a-z]+:/)) return;
+    $(e).attr('href', `${hrefPathPrefix}/${href}`);
+  });
+}
+
 function _indentedEltHtml($elt, i, filterFnOpt) {
     let lines = $elt.html().split('\n');
     if (filterFnOpt) lines = lines.filter(filterFnOpt);
     const indent = '                    '.substring(0,i);
     return lines.map((line) => `${indent}| ${line}`).join('\n');
 }
 
-function apiEntryJadeTemplate(baseHrefDepth, $breadcrumbs, $mainDiv) {
+function apiEntryJadeTemplate($, baseHrefDepth, $breadcrumbs, $mainDiv) {
     const baseHref = path.join(...Array(baseHrefDepth).fill('..'));
     // TODO/investigate: for some reason $breadcrumbs.html() is missing the <ol></ol>. We add it back in the template below.
+    _adjustAnchorHref($, $breadcrumbs, baseHref);
     const breadcrumbs = _indentedEltHtml($breadcrumbs, 6, (line) => !line.match(/^\s*$/));
+    _adjustAnchorHref($, $mainDiv, baseHref);
     const mainDivHtml = _indentedEltHtml($mainDiv, 4);
     // WARNING: since the following is Jade, indentation is significant.
     const result = `
@@ -217,8 +229,8 @@ include ${baseHref}/../_util-fns
 
 block head-extra
   // generated Dart API page template: head-extra
-  //- <base> is required because all the links in dartdoc generated pages are "pseudo-absolute"
-  base(href="${baseHref}")
+  //- <base> is no longer required
+  //- base(href="${baseHref}")
 
 block breadcrumbs
   // generated Dart API page template: breadcrumbs