fix: docs generation should maintain a stable relative path (emberjs#8598)

Author: runspired

docs-generator/compile-docs.js

@@ -29,16 +29,54 @@ function generateOptions() {
   return Y.Project.init(config);
 }
 
+function rewritePath(filePath) {
+  if (filePath.startsWith('../packages')) {
+    return filePath.replace('../packages/', '../');
+  }
+  if (filePath.startsWith('../')) {
+    return filePath.replace('../', '../../');
+  }
+  return filePath;
+}
+
 async function main() {
   const options = generateOptions();
 
   const yuidocCompiler = new Y.YUIDoc(options);
-  const json = yuidocCompiler.run();
-  const builder = new Y.DocBuilder(options, json);
+  const initialJson = yuidocCompiler.run();
+
+  const builder = new Y.DocBuilder(options, initialJson);
 
   await new Promise((resolve) => {
     builder.compile(resolve);
   });
+
+  const dataFile = path.join(__dirname, '../packages/-ember-data/dist/docs/data.json');
+  const json = JSON.parse(fs.readFileSync(dataFile));
+
+  const newFiles = {};
+  Object.keys(json.files).forEach((key) => {
+    const newKey = rewritePath(key);
+    newFiles[newKey] = json.files[key];
+    newFiles[newKey].name = newKey;
+  });
+  json.files = newFiles;
+
+  Object.keys(json.classes).forEach((key) => {
+    const val = json.classes[key];
+    if (val.file) {
+      val.file = rewritePath(val.file);
+    }
+  });
+
+  Object.keys(json.modules).forEach((key) => {
+    const val = json.modules[key];
+    if (val.file) {
+      val.file = rewritePath(val.file);
+    }
+  });
+
+  fs.writeFileSync(dataFile, JSON.stringify(json, null, 2));
 }
 
 main();

tests/docs/index.js

@@ -1,4 +1,7 @@
 'use strict';
+const path = require('path');
+const fs = require('fs');
+
 const QUnit = require('qunit');
 
 const { test } = QUnit;
@@ -38,6 +41,7 @@ QUnit.module('Docs coverage', function (hooks) {
       const module = docs.modules[moduleName];
       if (isOwnModule(module)) {
         test(`${moduleName} is configured correctly`, function (assert) {
+          assert.ok(docs.files[module.file], `${moduleName} has a file in ${linkItem(module)}`);
           assert.strictEqual(module.tag, 'main', `${moduleName} is tagged as main in ${linkItem(module)}`);
           assert.true(isNonEmptyString(module.description), `${moduleName} has a description in ${linkItem(module)}`);
           assert.false(
@@ -56,6 +60,7 @@ QUnit.module('Docs coverage', function (hooks) {
         return;
       }
       test(`Class ${className} is documented correctly at ${linkItem(def)}`, function (assert) {
+        assert.ok(docs.files[def.file], `${className} has a file`);
         assert.true(
           def.access === 'public' || def.access === 'private',
           `${def.name} must declare either as either @internal @private or @public`
@@ -150,6 +155,16 @@ QUnit.module('Docs coverage', function (hooks) {
       );
     });
   });
+
+  QUnit.module('files', function (hooks) {
+    test(`All files have meaningful paths`, function (assert) {
+      const root = path.join(__dirname, '../../packages/-ember-data');
+      Object.keys(docs.files).forEach((fileName) => {
+        const filePath = path.join(root, fileName);
+        assert.true(fs.existsSync(filePath), `${fileName} is resolvable as ${filePath}`);
+      });
+    });
+  });
 });
 
 function setDifference(setA, setB) {