build: check broken links in generated docs (#358)

* build: check dead links on Kokoro

* recursive crawl local links

* fix dead links in timestamp

* fix links

* fix broken links

.jsdoc.js

@@ -20,7 +20,7 @@ module.exports = {
   opts: {
     readme: './README.md',
     package: './package.json',
-    template: './node_modules/ink-docstrap/template',
+    template: './node_modules/jsdoc-baseline',
     recurse: true,
     verbose: true,
     destination: './docs/'

.kokoro/docs.sh

@@ -23,3 +23,11 @@ cd $(dirname $0)/..
 npm install
 
 npm run docs
+
+# Check broken links
+BIN=./node_modules/.bin
+
+npm install broken-link-checker
+npm install http-server
+$BIN/http-server -p 8080 docs/ &
+$BIN/blc -r http://localhost:8080

package.json

@@ -96,7 +96,7 @@
     "eslint-plugin-prettier": "^3.0.0",
     "google-proto-files": "^0.18.0",
     "gts": "^0.9.0",
-    "ink-docstrap": "git+https://github.com/docstrap/docstrap.git",
+    "jsdoc-baseline": "git+https://github.com/hegemonic/jsdoc-baseline.git",
     "intelli-espower-loader": "^1.0.1",
     "jsdoc": "^3.5.5",
     "mocha": "^5.2.0",

src/index.ts

@@ -98,10 +98,10 @@ export interface LoggingOptions extends gax.GoogleAuthOptions {
  *
  * @class
  *
- * @see [What is Stackdriver Logging?]{@link https://cloud.google.com/logging/docs}
- * @see [Introduction to the Stackdriver Logging API]{@link https://cloud.google.com/logging/docs/api}
- * @see [Logging to Stackdriver from Bunyan]{@link https://www.npmjs.com/package/@google-cloud/logging-bunyan}
- * @see [Logging to Stackdriver from Winston]{@link https://www.npmjs.com/package/@google-cloud/logging-winston}
+ * @see [What is Stackdriver Logging?](https://cloud.google.com/logging/docs)
+ * @see [Introduction to the Stackdriver Logging API](https://cloud.google.com/logging/docs/api)
+ * @see [Logging to Stackdriver from Bunyan](https://www.npmjs.com/package/@google-cloud/logging-bunyan)
+ * @see [Logging to Stackdriver from Winston](https://www.npmjs.com/package/@google-cloud/logging-winston)
  *
  * @param {ClientConfig} [options] Configuration options.
  *

src/v2/doc/google/api/doc_distribution.js

@@ -44,7 +44,7 @@
  *   The sum of squared deviations from the mean of the values in the
  *   population. For values x_i this is:
  *
- *       Sum[i=1..n](https://cloud.google.com(x_i - mean)^2)
+ *       Sum\[i=1..n](x_1 - mean)^2
  *
  *   Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition
  *   describes Welford's method for accumulating this sum in one pass.

src/v2/doc/google/protobuf/doc_timestamp.js

@@ -87,13 +87,11 @@
  * 01:30 UTC on January 15, 2017.
  *
  * In JavaScript, one can convert a Date object to this format using the
- * standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+ * standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
  * method. In Python, a standard `datetime.datetime` object can be converted
  * to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)
  * with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
- * can use the Joda Time's [`ISODateTimeFormat.dateTime()`](https://cloud.google.com
- * http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--
- * ) to obtain a formatter capable of generating timestamps in this format.
+ * can use the Joda Time's [`ISODateTimeFormat.dateTime()`](https://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--) to obtain a formatter capable of generating timestamps in this format.
  *
  * @property {number} seconds
  *   Represents seconds of UTC time since Unix epoch

synth.py

@@ -45,6 +45,22 @@
 templates = common_templates.node_library(source_location='build/src')
 s.copy(templates)
 
+# [START fix-dead-link]
+s.replace('**/doc/google/protobuf/doc_timestamp.js',
+        'https:\/\/cloud\.google\.com[\s\*]*http:\/\/(.*)[\s\*]*\)',
+        r"https://\1)")
+
+s.replace('**/doc/google/protobuf/doc_timestamp.js',
+        'toISOString\]',
+        'toISOString)')
+# [END fix-dead-link]
+
+s.replace('src/v2/doc/google/api/doc_distribution.js',
+        r"Sum\[i=1\.\.n\]\(https:\/\/cloud\.google\.com\(x_i - mean\)\^2\)",
+        "Sum\[i=1..n](x_1 - mean)^2")
+
+
+
 # Node.js specific cleanup
 subprocess.run(["npm", "install"])
 subprocess.run(["npm", "run", "fix"])