#93 - Generate docs source links in one build

docs/classes/Resources.Configuration.html

@@ -12,7 +12,7 @@
 <li><a href="" aria-current="page">Configuration</a></li></ul>
 <h1>Class Configuration</h1></div><aside class="tsd-sources">
 <ul>
-<li>Defined in Configuration.ts:3</li></ul></aside>
+<li>Defined in <a href="https://github.com/ordercloud-api/ordercloud-javascript-sdk/blob/master/src/Configuration.ts#L3">Configuration.ts:3</a></li></ul></aside>
 <section class="tsd-panel-group tsd-index-group">
 <section class="tsd-panel tsd-index-panel">
 <details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>
@@ -34,7 +34,7 @@ <h3 class="tsd-anchor-link" id="get"><span>Get</span><a href="#get" aria-label="
 <div class="tsd-description">
 <h4 class="tsd-returns-title">Returns <a href="../interfaces/SdkConfiguration.html" class="tsd-signature-type tsd-kind-interface">SdkConfiguration</a></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in Configuration.ts:38</li></ul></aside></div></li></ul></section>
+<li>Defined in <a href="https://github.com/ordercloud-api/ordercloud-javascript-sdk/blob/master/src/Configuration.ts#L38">Configuration.ts:38</a></li></ul></aside></div></li></ul></section>
 <section class="tsd-panel tsd-member">
 <h3 class="tsd-anchor-link" id="set"><span>Set</span><a href="#set" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <ul class="tsd-signatures">
@@ -47,7 +47,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <li><span><span class="tsd-kind-parameter">config</span>: <a href="../interfaces/SdkConfiguration.html" class="tsd-signature-type tsd-kind-interface">SdkConfiguration</a></span></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in Configuration.ts:29</li></ul></aside></div></li></ul></section></section></details></div>
+<li>Defined in <a href="https://github.com/ordercloud-api/ordercloud-javascript-sdk/blob/master/src/Configuration.ts#L29">Configuration.ts:29</a></li></ul></aside></div></li></ul></section></section></details></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">

docs/variables/Configuration.html

@@ -12,7 +12,7 @@
 <h1>Variable Configuration</h1></div>
 <div class="tsd-signature"><span class="tsd-kind-variable">Configuration</span><span class="tsd-signature-symbol">:</span> <a href="../classes/Resources.Configuration.html" class="tsd-signature-type tsd-kind-class">Configuration</a></div><aside class="tsd-sources">
 <ul>
-<li>Defined in Configuration.ts:49</li></ul></aside></div>
+<li>Defined in <a href="https://github.com/ordercloud-api/ordercloud-javascript-sdk/blob/master/src/Configuration.ts#L49">Configuration.ts:49</a></li></ul></aside></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">

package.json

@@ -41,7 +41,7 @@
     "prebuild:sdk": "npm run clean:dist && npm run generate-sdk && npm run beautify",
     "build:sdk": "rollup --config",
     "postbuild:sdk": "shx cp dist/index.d.ts dist/index.esm.d.ts",
-    "build:docs": "typedoc",
+    "build:docs": "typedoc && node scripts/check-docs-source-links.js",
     "test": "npm run test:browser && npm run test:server",
     "test:browser": "jest --config tests/config/browser.config.js",
     "test:server": "jest --config tests/config/server.config.js",

scripts/check-docs-source-links.js

@@ -0,0 +1,56 @@
+const fs = require('fs')
+const path = require('path')
+
+const docsDir = path.join(__dirname, '..', 'docs')
+const example = path.join(docsDir, 'classes', 'Resources.Addresses.html')
+const linkedSource = /Defined in <a href="https:\/\/github\.com\/ordercloud-api\/ordercloud-javascript-sdk\//g
+const unlinkedSource = /Defined in (?!<a href="https:\/\/github\.com\/ordercloud-api\/ordercloud-javascript-sdk\/)/g
+
+function walk(dir, files) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walk(fullPath, files)
+    } else if (entry.name.endsWith('.html')) {
+      files.push(fullPath)
+    }
+  }
+  return files
+}
+
+if (!fs.existsSync(example)) {
+  console.error(
+    `Missing ${path.relative(process.cwd(), example)}. Docs must be generated before checking source links.`
+  )
+  process.exit(1)
+}
+
+const failures = []
+let linkedCount = 0
+
+for (const file of walk(docsDir, [])) {
+  const html = fs.readFileSync(file, 'utf8')
+  const bad = html.match(unlinkedSource)
+  if (bad) {
+    failures.push(`${path.relative(docsDir, file)} (${bad.length})`)
+  }
+  const good = html.match(linkedSource)
+  if (good) {
+    linkedCount += good.length
+  }
+}
+
+if (linkedCount === 0) {
+  console.error('Docs contain no GitHub source links.')
+  process.exit(1)
+}
+
+if (failures.length) {
+  console.error('Docs source links were not generated:')
+  for (const failure of failures) {
+    console.error(`  ${failure}`)
+  }
+  process.exit(1)
+}
+
+console.log(`Docs source links ok (${linkedCount} GitHub links).`)