From 56f0ccd45da29a92accbe655f54c5eb9b51f93fb Mon Sep 17 00:00:00 2001 From: Jonathan Lui Date: Tue, 15 Jan 2019 10:10:18 -0800 Subject: [PATCH] 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 | 2 +- .kokoro/docs.sh | 8 ++++++++ package.json | 2 +- src/index.ts | 8 ++++---- src/v2/doc/google/api/doc_distribution.js | 2 +- src/v2/doc/google/protobuf/doc_timestamp.js | 6 ++---- synth.py | 16 ++++++++++++++++ 7 files changed, 33 insertions(+), 11 deletions(-) diff --git a/.jsdoc.js b/.jsdoc.js index 2b829d39..33280bcc 100644 --- a/.jsdoc.js +++ b/.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/' diff --git a/.kokoro/docs.sh b/.kokoro/docs.sh index 3af31934..8ca19ce2 100755 --- a/.kokoro/docs.sh +++ b/.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 diff --git a/package.json b/package.json index e16e7084..84b82f6b 100644 --- a/package.json +++ b/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", diff --git a/src/index.ts b/src/index.ts index 277b02b1..72d18d29 100644 --- a/src/index.ts +++ b/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. * diff --git a/src/v2/doc/google/api/doc_distribution.js b/src/v2/doc/google/api/doc_distribution.js index 7fd05a5f..d4e28029 100644 --- a/src/v2/doc/google/api/doc_distribution.js +++ b/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. diff --git a/src/v2/doc/google/protobuf/doc_timestamp.js b/src/v2/doc/google/protobuf/doc_timestamp.js index 1ebe2e6e..1cc64cbe 100644 --- a/src/v2/doc/google/protobuf/doc_timestamp.js +++ b/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 diff --git a/synth.py b/synth.py index d61abaeb..8a6cd67a 100644 --- a/synth.py +++ b/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"])