Support standalone docs apps (#409)

ef4 · samselikoff · commit 5fb1cc8093ef · 2019-11-01T18:34:58.000-04:00
This makes it possible to separate your docs application from your addon's dummy app. Fixes #383. The way it works is: - you're still required to keep both the addon and the docs app in the same repo (so we don't need to worry about separately versioning each) - but they can be peers or subdirectories of each other - in your docs application you add ember-cli-addon-docs - in your docs application you must set the `documentingAddonAt` option to point at the path of the actual addon. As a side-effect of refactoring the way "Edit this page" links work, I think I also fixed them for API-docs pages in all addon docs sites (not just ones using this new architecture).
diff --git a/addon/adapters/-addon-docs.js b/addon/adapters/-addon-docs.js
@@ -1,5 +1,5 @@
 import DS from 'ember-data';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 import { inject as service } from '@ember/service';
 
 export default DS.Adapter.extend({
diff --git a/addon/components/api/x-class/component.js b/addon/components/api/x-class/component.js
@@ -3,7 +3,7 @@ import { computed } from '@ember/object';
 import { or } from '@ember/object/computed';
 import { capitalize } from '@ember/string';
 import { memberFilter }  from '../../../utils/computed';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 
 const { showImportPaths } = config['ember-cli-addon-docs'];
 
diff --git a/addon/components/api/x-section/component.js b/addon/components/api/x-section/component.js
@@ -1,7 +1,7 @@
 import Component from '@ember/component';
 import { computed } from '@ember/object';
 import layout from './template';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 
 const { showImportPaths } = config['ember-cli-addon-docs'];
 
diff --git a/addon/components/docs-header/component.js b/addon/components/docs-header/component.js
@@ -1,6 +1,6 @@
 import Component from '@ember/component';
 import layout from './template';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 import { computed } from '@ember/object';
 import { classify } from '@ember/string';
 import { addonLogo, addonPrefix } from 'ember-cli-addon-docs/utils/computed';
diff --git a/addon/components/docs-header/search-box/component.js b/addon/components/docs-header/search-box/component.js
@@ -3,7 +3,7 @@ import layout from './template';
 import { EKMixin, keyUp } from 'ember-keyboard';
 import { on } from '@ember/object/evented';
 import { task } from 'ember-concurrency';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 import { inject as service } from '@ember/service';
 import { formElementHasFocus } from 'ember-cli-addon-docs/keyboard-config';
 
@@ -18,7 +18,7 @@ export default Component.extend(EKMixin, {
   query: null,
 
   keyboardActivated: true,
-  
+
   didInsertElement() {
     this._super();
 
diff --git a/addon/components/docs-header/search-results/component.js b/addon/components/docs-header/search-results/component.js
@@ -5,7 +5,7 @@ import { EKMixin, keyUp, keyDown } from 'ember-keyboard';
 import { on } from '@ember/object/evented';
 import { computed } from '@ember/object';
 import { task } from 'ember-concurrency';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 
 const projectName = config['ember-cli-addon-docs'].projectName;
 
@@ -20,7 +20,7 @@ export default Component.extend(EKMixin, {
   selectedIndex: null,
 
   keyboardActivated: true,
-  
+
   didInsertElement() {
     this._super();
 
diff --git a/addon/components/docs-header/version-selector/component.js b/addon/components/docs-header/version-selector/component.js
@@ -2,7 +2,7 @@ import Component from '@ember/component';
 import { inject as service } from '@ember/service';
 import layout from './template';
 import { reads } from '@ember/object/computed';
-// import config from 'dummy/config/environment';
+// import config from 'ember-get-config';
 import { computed } from '@ember/object';
 import { A } from '@ember/array';
 import { getOwner } from '@ember/application';
diff --git a/addon/components/docs-hero/component.js b/addon/components/docs-hero/component.js
@@ -1,7 +1,7 @@
 import Component from '@ember/component';
 import layout from './template';
 import { addonPrefix, unprefixedAddonName } from 'ember-cli-addon-docs/utils/computed';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 import { classify } from '@ember/string';
 const { projectName, projectDescription } = config['ember-cli-addon-docs'];
 
diff --git a/addon/components/docs-snippet/component.js b/addon/components/docs-snippet/component.js
@@ -1,7 +1,8 @@
 import { computed } from '@ember/object';
 import Component from '@ember/component';
 import layout from './template';
-import Snippets from "dummy/snippets";
+import config from 'ember-get-config';
+import require from 'require';
 
 /**
   A snippet component for demonstrating some code
@@ -80,8 +81,10 @@ export default Component.extend({
       name += '.hbs';
     }
 
+    let snippet = require(config.modulePrefix + "/snippets")[name] || "";
+
     return this._unindent(
-      (Snippets[name] || "")
+      snippet
         .replace(/^(\s*\n)*/, '')
         .replace(/\s*$/, '')
     );
diff --git a/addon/components/docs-viewer/x-main/component.js b/addon/components/docs-viewer/x-main/component.js
@@ -4,7 +4,7 @@ import { bind } from '@ember/runloop';
 import { computed } from '@ember/object';
 import appFiles from 'ember-cli-addon-docs/app-files';
 import addonFiles from 'ember-cli-addon-docs/addon-files';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 import { getOwner } from '@ember/application';
 
 import layout from './template';
@@ -70,26 +70,38 @@ export default Component.extend({
       return;
     }
 
-    path = path.replace(/\./g, '/');
-
-    let { projectHref, projectPathInRepo, primaryBranch } = config['ember-cli-addon-docs'];
-    let projectPath = projectPathInRepo ? `/${projectPathInRepo}/` : '/';
-    let rootEditUrl = `${projectHref}/edit/${primaryBranch}${projectPath}`;
+    let match = this._locateFile(path);
+    if (match) {
+      let { projectHref, addonPathInRepo, docsAppPathInRepo, primaryBranch } = config['ember-cli-addon-docs'];
+      let parts = [projectHref, 'edit', primaryBranch];
+      if (match.inTree === 'addon') {
+        parts.push(addonPathInRepo);
+      } else {
+        parts.push(docsAppPathInRepo);
+      }
+      parts.push(match.file);
+      return parts.filter(Boolean).join('/');
+    }
+  }),
 
+  _locateFile(path) {
+    path = path.replace(/\./g, '/');
     if (path === 'docs/api/item') {
-      let { path } = getOwner(this).lookup('route:application').paramsFor('docs.api.item');
-      let file = addonFiles.find(f => f.match(path));
-
+      let { projectName } = config['ember-cli-addon-docs'];
+      let model = getOwner(this).lookup('route:application').modelFor('docs.api.item');
+      let filename = model.get('file').replace(new RegExp(`^${projectName}/`), '');
+      let file = addonFiles.find(f => f.match(filename));
       if (file) {
-        return `${rootEditUrl}addon/${file}`;
+        return { file, inTree: 'addon' };
       }
     } else {
       let file = appFiles
         .filter(file => file.match(/\.(hbs|md)$/))
         .find(file => file.match(path));
-
-      return `${rootEditUrl}tests/dummy/app/${file}`;
+      if (file) {
+        return { file, inTree: 'app' };
+      }
     }
-  })
+  }
 
 });
diff --git a/addon/components/docs-viewer/x-nav/component.js b/addon/components/docs-viewer/x-nav/component.js
@@ -2,7 +2,7 @@ import { computed } from '@ember/object';
 import { inject as service } from '@ember/service';
 import Component from '@ember/component';
 import layout from './template';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 import { classify } from '@ember/string';
 import { addonLogo } from 'ember-cli-addon-docs/utils/computed';
 
diff --git a/addon/routes/docs.js b/addon/routes/docs.js
@@ -1,5 +1,5 @@
 import Route from '@ember/routing/route';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 
 const projectName = config['ember-cli-addon-docs'].projectName;
 
diff --git a/addon/services/docs-search.js b/addon/services/docs-search.js
@@ -2,7 +2,7 @@ import Service, { inject as service } from '@ember/service';
 import { getOwner } from '@ember/application';
 import { computed } from '@ember/object';
 import lunr from 'lunr';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 
 const { Index, Query } = lunr;
 
diff --git a/addon/services/project-version.js b/addon/services/project-version.js
@@ -2,7 +2,7 @@ import Service, { inject as service } from '@ember/service';
 import { getOwner } from '@ember/application';
 import { computed } from '@ember/object';
 import { task } from 'ember-concurrency';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 import { assign } from '@ember/polyfills';
 
 const { latestVersionName } = config['ember-cli-addon-docs'];
diff --git a/index.js b/index.js
@@ -53,17 +53,35 @@ module.exports = {
   },
 
   config(env, baseConfig) {
-    let repo = this.parent.pkg.repository;
+    let pkg = this.parent.pkg;
+    if (this._documentingAddonAt()) {
+      pkg = require(path.join(this._documentingAddonAt(), 'package.json'));
+    }
+
+    let repo = pkg.repository;
     let info = require('hosted-git-info').fromUrl(repo.url || repo);
     let userConfig = this._readUserConfig();
 
+    let docsAppPathInRepo = path.relative(
+      this._getRepoRoot(),
+      path.join(
+        path.resolve(path.dirname(this.project.configPath()), '..'),
+        'app'
+      )
+    );
+
+    let addonPathInRepo = this._documentingAddonAt()
+      ? path.relative(this._getRepoRoot(), path.join(this._documentingAddonAt(), 'addon'))
+      : path.relative(this._getRepoRoot(), path.join(this.project.root, 'addon'));
+
     let config = {
       'ember-cli-addon-docs': {
-        projectName: this.parent.pkg.name,
-        projectDescription: this.parent.pkg.description,
-        projectTag: this.parent.pkg.version,
+        projectName: pkg.name,
+        projectDescription: pkg.description,
+        projectTag: pkg.version,
         projectHref: info && info.browse(),
-        projectPathInRepo: path.relative(this._getRepoRoot(), this.project.root),
+        docsAppPathInRepo,
+        addonPathInRepo,
         primaryBranch: userConfig.getPrimaryBranch(),
         latestVersionName: LATEST_VERSION_NAME,
         deployVersion: 'ADDON_DOCS_DEPLOY_VERSION',
@@ -92,11 +110,24 @@ module.exports = {
     if (includer.parent) {
       throw new Error(`ember-cli-addon-docs should be in your package.json's devDependencies`);
     } else if (includer.name === this.project.name()) {
-      throw new Error(`ember-cli-addon-docs only currently works with addons, not applications`);
+      if (this._documentingAddonAt()) {
+        // we're being used in a standalone documentation app that documents an
+        // addon but is not that addon's dummy app.
+      } else {
+        throw new Error(`to use ember-cli-addon-docs in an application (as opposed to an addon) you must set documentingAddonAt`);
+      }
     }
 
     includer.options.includeFileExtensionInSnippetNames = includer.options.includeFileExtensionInSnippetNames || false;
-    includer.options.snippetSearchPaths = includer.options.snippetSearchPaths || ['tests/dummy/app'];
+    if (!includer.options.snippetSearchPaths) {
+      if (this._documentingAddonAt()) {
+        // we are a standalone app, so our code is here
+        includer.options.snippetSearchPaths = ['app'];
+      } else {
+        // we are inside the addon, so our code is here
+        includer.options.snippetSearchPaths = ['tests/dummy/app'];
+      }
+    }
     includer.options.snippetRegexes = Object.assign({}, {
       begin: /{{#(?:docs-snippet|demo.example)\sname=(?:"|')(\S+)(?:"|')/,
       end: /{{\/(?:docs-snippet|demo.example)}}/,
@@ -187,8 +218,8 @@ module.exports = {
 
   treeForAddon(tree) {
     let dummyAppFiles = new FindDummyAppFiles([ this.app.trees.app ]);
-    let addonFiles = new FindAddonFiles([ 'addon' ].filter(dir => fs.existsSync(dir)));
-
+    let addonToDocument = this._documentingAddon();
+    let addonFiles = new FindAddonFiles([path.join(addonToDocument.root, 'addon')]);
     return this._super(new MergeTrees([ tree, dummyAppFiles, addonFiles ]));
   },
 
@@ -209,17 +240,16 @@ module.exports = {
   },
 
   postprocessTree(type, tree) {
-    let parentAddon = this.parent.findAddonByName(this.parent.name());
-    if (!parentAddon || type !== 'all') { return tree; }
+    let addonToDocument = this._documentingAddon();
+    if (!addonToDocument || type !== 'all') { return tree; }
 
     let PluginRegistry = require('./lib/models/plugin-registry');
     let DocsCompiler = require('./lib/broccoli/docs-compiler');
     let SearchIndexer = require('./lib/broccoli/search-indexer');
 
     let project = this.project;
     let docsTrees = [];
-
-    this.addonOptions.projects.main = this.addonOptions.projects.main || generateDefaultProject(parentAddon);
+    this.addonOptions.projects.main = this.addonOptions.projects.main || generateDefaultProject(addonToDocument);
 
     for (let projectName in this.addonOptions.projects) {
       let addonSourceTree = this.addonOptions.projects[projectName];
@@ -229,12 +259,12 @@ module.exports = {
       let docsGenerators = pluginRegistry.createDocsGenerators(addonSourceTree, {
         destDir: 'docs',
         project,
-        parentAddon
+        parentAddon: addonToDocument
       });
 
       docsTrees.push(
         new DocsCompiler(docsGenerators, {
-          name: projectName === 'main' ? parentAddon.name : projectName,
+          name: projectName === 'main' ? addonToDocument.name : projectName,
           project
         })
       );
@@ -276,6 +306,33 @@ module.exports = {
       this._repoRoot = require('git-repo-info')().root;
     }
     return this._repoRoot;
+  },
+
+  // returns the absolute path to the addon we're documenting when
+  // ember-cli-addon-docs is being used by an *app* (not an addon) that has
+  // explicitly set `documentingAddonAt`.
+  _documentingAddonAt() {
+    if (this._cachedDocumentingAddonAt === undefined && this.app) {
+      if (this.app.options['ember-cli-addon-docs'] && this.app.options['ember-cli-addon-docs'].documentingAddonAt) {
+        this._cachedDocumentingAddonAt = path.resolve(this.project.root, this.app.options['ember-cli-addon-docs'].documentingAddonAt);
+      } else {
+        this._cachedDocumentingAddonAt = null;
+      }
+    }
+    return this._cachedDocumentingAddonAt;
+  },
+
+  _documentingAddon() {
+    let addon;
+    if (this._documentingAddonAt()) {
+      addon = this.project.addons.find(a => a.root === this._documentingAddonAt())
+      if (!addon) {
+        throw new Error(`You set documentingAddonAt to point at ${this._documentingAddonAt()} but that addon does not appear to be present in this app.`);
+      }
+    } else {
+      addon = this.parent.findAddonByName(this.parent.name());
+    }
+    return addon;
   }
 };
 
diff --git a/package.json b/package.json
@@ -55,6 +55,7 @@
     "ember-data": "2.x - 3.x",
     "ember-fetch": "^6.7.1",
     "ember-fetch-adapter": "^0.4.3",
+    "ember-get-config": "^0.2.4",
     "ember-href-to": "^1.15.1",
     "ember-keyboard": "^4.0.0",
     "ember-modal-dialog": "^3.0.0-beta.4",
diff --git a/tests/acceptance/sandbox/api/components-test.js b/tests/acceptance/sandbox/api/components-test.js
@@ -2,7 +2,7 @@ import { module, test } from 'qunit';
 import { setupApplicationTest } from 'ember-qunit';
 import setupMirage from 'ember-cli-mirage/test-support/setup-mirage';
 import { currentURL, visit, waitUntil } from '@ember/test-helpers';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 
 import modulePage from '../../../pages/api/module';
 
@@ -58,11 +58,11 @@ module('Acceptance | Sandbox | API | components', function(hooks) {
 
   module('in a nested directory within a repo', function(hooks) {
     hooks.beforeEach(function() {
-      config['ember-cli-addon-docs'].projectPathInRepo = 'packages/foo-bar';
+      config['ember-cli-addon-docs'].docsAppPathInRepo = 'packages/foo-bar/tests/dummy/app';
     });
 
     hooks.afterEach(function() {
-      config['ember-cli-addon-docs'].projectPathInRepo = '';
+      config['ember-cli-addon-docs'].docsAppPathInRepo = '';
     });
 
     test('welcome page \'Edit this page\' link is correct', async function(assert) {
diff --git a/tests/acceptance/version-selector-test.js b/tests/acceptance/version-selector-test.js
@@ -2,7 +2,7 @@ import { module, test } from 'qunit';
 import { setupApplicationTest } from 'ember-qunit';
 import setupMirage from 'ember-cli-mirage/test-support/setup-mirage';
 import { visit, click } from '@ember/test-helpers';
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 
 module('Acceptance | Version selector test', function(hooks) {
   setupApplicationTest(hooks);
diff --git a/tests/dummy/mirage/config.js b/tests/dummy/mirage/config.js
@@ -1,4 +1,4 @@
-import config from 'dummy/config/environment';
+import config from 'ember-get-config';
 const projectTag = config['ember-cli-addon-docs'].projectTag;
 
 export default function() {
diff --git a/yarn.lock b/yarn.lock
