chore: fix broken links and transform API links for dart docs

- Dart non-api doc pages w/ links to API entries will now have those
links translated from a TS API reference URL to a Dart API reference
URL.
- Created and ran a link checker to verify that all such links to API
entries refer to Dart.
- Fixed links to pages that have moved:
 - JS & Dart: `i18n` is under now `cookbook` not `guide`
 - Dart: testing page is now directly under guide.

Contributes to #1895
Fixes #2273

Author: chalin

public/docs/_layout.jade

@@ -1,5 +1,22 @@
 //- WARNING: _layout.jade and _layout-dart-api.jade should match in terms of content
 //- except that one uses Harp partial/yield and the other uses Jade extends/include.
+
+- function tsApiHrefToDart(match, hrefApi, dontcare1, urlRest) {
+-   // Simple argument values:
+-   // hrefApi: href="../api/
+-   // urlRest: core/index/ViewChild-var.html"
+-   // console.log(`got match on ${match}, 1: ${hrefApi}, 3: ${urlRest}`);
+-   var matches = urlRest.match(/^(\w*)\/index\/(\w*)-(\w*)(\.html")$/);
+-   // console.log(`urlRest matches ${matches}`);
+-   if (!matches) return match; // leave unchanged
+-   var i = 1; // matches[0] corresponds to the fully matched result
+-   var libName = matches[i++];
+-   var apiPageEntryName = matches[i++];
+-   var apiEntryKind = matches[i++];
+-   var suffix = matches[i++];
+-   return hrefApi + 'angular2.' + libName + '/' + apiPageEntryName + '-class' + suffix;
+- }
+
 if jade2ng
   .side-nav--offset
     != partial("../_includes/_hero")
@@ -35,8 +52,10 @@ else
           article(class="l-content-small grid-fluid docs-content")
             != yield
         else
+          - var isDart = current.path[1] === 'dart';
+          - var regex = /(href=\"(\.?\.\/)*api\/)(.*")/g;
           article(class="l-content-small grid-fluid docs-content")
-            != yield
+            != !isDart ? yield : yield.replace(regex, tsApiHrefToDart)
               if (current.path[3] == 'guide' || current.path[3] == 'tutorial') && current.path[4]
                 != partial("../_includes/_next-item")
 

public/docs/dart/latest/guide/i18n.jade

@@ -362,7 +362,7 @@ block ctor-syntax
 
 .l-sub-section
   :marked
-    Learn more in [Testing](../testing/index.html).
+    Learn more in [Testing](./testing.html).
 
 :marked
   ### When the service needs a service

public/docs/js/latest/guide/i18n.jade

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# This script currently requires that the site have been generated
+# under $SITE and that it is being served via http://localhost:8080.
+
+set -e -o pipefail
+
+[[ -z "$NGIO_ENV_DEFS" ]] && . ./scripts/env-set.sh > /dev/null
+if [[ "x$1" == "x-v" ]]; then VERBOSE=1; shift; fi
+
+SITE=./www
+
+CHECK_FOR=dart-bad-api-links
+
+LOGFILE_PREFIX=$CHECK_FOR-log
+LOGFILE_FULL=$TMP/$LOGFILE_PREFIX-full.txt
+LOGFILE=$TMP/$LOGFILE_PREFIX.txt
+
+if [[ ! -d $SITE ]]; then
+    echo "Missing site folder $SITE"
+    exit 1;
+fi
+
+cd $SITE
+echo "" > $LOGFILE_FULL
+
+# We don't check cookbook pages since they are all empty.
+# We don't check api pages because there are currently too many broken links.
+for f in docs/dart/latest/{,guide/,tutorial/}*.html; do
+  echo "Checking links in $f";
+  $(npm bin)/blc -e --get http://localhost:8080/$f >> $LOGFILE_FULL
+done
+echo ""
+
+echo "Listing broken links, if any:"
+grep -i broken $LOGFILE_FULL | grep -v Finished || true
+echo ""
+
+echo "Listing links to TS api pages from Dart docs pages, if any:"
+grep /api/ $LOGFILE_FULL | grep -v '/api/$' | grep -v /angular2. || true
+echo ""
+
+echo "For details consult the full log $LOGFILE_FULL"