Merge pull request #166 from ember-learn/refactor/generalize-modules-links-and-api

[refactor] Simplify and generalize Module links

Author: pzuraq

addon/components/api/x-import-path/component.js

@@ -1,11 +1,7 @@
 import Component from '@ember/component';
 import layout from './template';
-import config from 'dummy/config/environment';
-
-const projectName = config['ember-cli-addon-docs'].projectName;
 
 export default Component.extend({
   layout,
-  classNames: ['import-path'],
-  projectName
+  classNames: ['import-path']
 });

addon/components/api/x-import-path/template.hbs

@@ -7,4 +7,4 @@
 {{/if}}
 
 <span class="hljs-keyword">from</span>
-<span class="hljs-string">'{{projectName}}{{item.file}}'</span>;
+<span class="hljs-string">'{{item.file}}'</span>;

addon/components/docs-viewer/x-nav-item/component.js

@@ -11,6 +11,11 @@ export default Component.extend({
 
   didInsertElement() {
     this._super(...arguments);
+    let model = this.get('model');
+
+    if (typeof model === 'string' && model.includes('#')) {
+      return;
+    }
 
     next(() => {
       this.get('docsRoutes.items').addObject(this);

addon/components/docs-viewer/x-nav/template.hbs

@@ -49,9 +49,11 @@
                 {{/each}}
               {{else}}
                 {{#each-in items as |module items|}}
-                  <li class="docs-viewer__module-heading">
-                    {{module}}
-                  </li>
+                  {{subnav.item module
+                    (concat root '.api.item')
+                    (concat 'modules/' module)
+                    class="docs-viewer__module-heading"
+                  }}
 
                   {{#docs-viewer/x-nav-list as |subnav|}}
                     {{#each items as |item|}}

addon/routes/docs/api/item.js

@@ -5,19 +5,24 @@ export default Route.extend({
   model({ path }) {
     let item;
 
-    if (path.match(/^root\//)) {
+    if (path.match(/^modules\//)) {
       // Find by fully qualified id
-      let itemId = path.replace(/^root\//, '');
-      let [moduleId] = itemId.split('~');
+      let itemId = path.replace(/^modules\//, '');
+      let [moduleId] = itemId.split(/~|#/);
 
       let module = this.store.peekRecord('module', moduleId);
 
       item = module.get('components').findBy('id', itemId)
         || module.get('classes').findBy('id', itemId)
         || module;
     } else {
+      // Create a regex that will match modules by either the path, or the
+      // pod-path (/component, /route, etc)
+      let type = path.match(/^(.*)s\//)[1];
+      let pathRegex = new RegExp(`${path}(/${type})?$`);
+
       let modules = this.store.peekAll('module');
-      let matches = modules.filter(m => m.id.match(path));
+      let matches = modules.filter(m => m.id.match(pathRegex));
       let module = matches[0];
 
       assert(`no modules match the path '${path}'`, matches.length > 0);

ember-cli-build.js

@@ -2,6 +2,8 @@
 
 const EmberAddon = require('ember-cli/lib/broccoli/ember-addon');
 const Project = require('ember-cli/lib/models/project');
+const MergeTrees = require('broccoli-merge-trees');
+const Funnel = require('broccoli-funnel');
 
 module.exports = function(defaults) {
   let project = Project.closestSync(process.cwd());
@@ -21,9 +23,12 @@ module.exports = function(defaults) {
     },
     'ember-cli-addon-docs': {
       projects: {
-        sandbox: {
-          tree: 'sandbox'
-        }
+        sandbox: new MergeTrees([
+          new Funnel('sandbox/app', { destDir: 'sandbox' }),
+          new Funnel('sandbox', {
+            include: ['package.json', 'README.md']
+          })
+        ])
       }
     }
   });

index.js

@@ -10,14 +10,6 @@ const EmberApp = require('ember-cli/lib/broccoli/ember-app'); // eslint-disable-
 const Plugin = require('broccoli-plugin');
 const walkSync = require('walk-sync');
 
-const DEFAULT_PROJECTS = {
-  main: {
-    tree: null,
-    include: null,
-    includeTrees: ['addon']
-  }
-}
-
 module.exports = {
   name: 'ember-cli-addon-docs',
 
@@ -95,7 +87,7 @@ module.exports = {
     }
 
     this.addonOptions = Object.assign({}, includer.options['ember-cli-addon-docs']);
-    this.addonOptions.projects = Object.assign({}, DEFAULT_PROJECTS, this.addonOptions.projects);
+    this.addonOptions.projects = Object.assign({}, this.addonOptions.projects);
 
     includer.options.includeFileExtensionInSnippetNames = includer.options.includeFileExtensionInSnippetNames || false;
     includer.options.snippetSearchPaths = includer.options.snippetSearchPaths || ['tests/dummy/app'];
@@ -182,35 +174,10 @@ module.exports = {
     let project = this.project;
     let docsTrees = [];
 
-    for (let projectName in this.addonOptions.projects) {
-      let docProject = this.addonOptions.projects[projectName];
-
-      let addonSourceTree;
-
-      if (docProject.tree) {
-        addonSourceTree = docProject.tree;
-      } else {
-        let include = docProject.include || [];
-        let includeTrees = docProject.includeTrees || [];
-
-        let includeTreePaths = includeTrees.map(t => parentAddon.treePaths[t]);
-        let includeFunnels = [
-          // We need to be very careful to avoid triggering a watch on the addon root here
-          // because of https://github.com/nodejs/node/issues/15683
-          new Funnel(new UnwatchedDir(parentAddon.root), {
-            include: ['package.json', 'README.md']
-          })
-        ];
-
-        for (let path of include.concat(includeTreePaths)) {
-          let fullPath = `${parentAddon.root}/${path}`;
-          if (fs.existsSync(fullPath)) {
-            includeFunnels.push(new Funnel(fullPath, { destDir: path }));
-          }
-        }
+    this.addonOptions.projects.main = this.addonOptions.projects.main || generateDefaultProject(parentAddon);
 
-        addonSourceTree = new MergeTrees(includeFunnels);
-      }
+    for (let projectName in this.addonOptions.projects) {
+      let addonSourceTree = this.addonOptions.projects[projectName];
 
       let pluginRegistry = new PluginRegistry(project);
 
@@ -279,6 +246,33 @@ function findImporter(addon) {
   }
 }
 
+function generateDefaultProject(parentAddon) {
+  let includeFunnels = [
+    // We need to be very careful to avoid triggering a watch on the addon root here
+    // because of https://github.com/nodejs/node/issues/15683
+    new Funnel(new UnwatchedDir(parentAddon.root), {
+      include: ['package.json', 'README.md']
+    })
+  ];
+
+  let addonTreePath = path.join(parentAddon.root, parentAddon.treePaths['addon']);
+  let testSupportPath = path.join(parentAddon.root, parentAddon.treePaths['addon-test-support']);
+
+  if (fs.existsSync(addonTreePath)) {
+    includeFunnels.push(new Funnel(addonTreePath, {
+      destDir: parentAddon.name
+    }));
+  }
+
+  if (fs.existsSync(testSupportPath)) {
+    includeFunnels.push(new Funnel(testSupportPath, {
+      destDir: `${parentAddon.name}/test-support`
+    }));
+  }
+
+  return new MergeTrees(includeFunnels);
+}
+
 class FindDummyAppFiles extends Plugin {
   build() {
     let addonPath = this.inputPaths[0];

lib/broccoli/docs-compiler.js

@@ -72,76 +72,6 @@ function compileDocDescriptions(modules) {
   });
 }
 
-function stripAppAddonDirs(modules) {
-
-  modules.forEach((module) => {
-    module.file = module.file.replace(/^(app|addon)/, '');
-  });
-
-  eachRelationship(modules, (relationship) => {
-    relationship.forEach((item) => {
-      if (item.file) item.file = item.file.replace(/^(app|addon)/, '');
-      if (item.name) item.name = item.name.replace(/^(app|addon)/, '');
-    });
-  });
-}
-
-/**
- * "Hoists" default exports from a given module. This is particularly useful
- * for class files, which generally only export a single default class and
- * would normally look like this:
- *
- * /classes/foo
- *   FooClass
- * /classes/bar
- *   BarClass
- *
- * Instead they become this:
- *
- * /classes
- *   FooClass
- *   BarClass
- *
- * Since these are the only exports of that type and the default, users can
- * generally infer that they can import the class from the file with the same
- * name as the class or component (in many cases this also doesn't matter
- * since the affected classes will be resolved).
- *
- * If a file has named exports they will continue to appear in that module:
- *
- * /classes
- *   FooClass
- * /classes/foo
- *   HelperClass
- *
- * @param {Object} modules
- */
-function hoistDefaults(modules) {
-  for (let m in modules) {
-    let module = modules[m];
-    let parentModulePath = path.dirname(m);
-
-    let value = _.remove(module, { isDefault: true });
-
-    if (value) {
-      modules[parentModulePath] = (modules[parentModulePath] || []).concat(value);
-    }
-  }
-
-  // Remove any modules without exports now that hoisting is done
-  for (let m in modules) {
-    let module = modules[m];
-
-    if (module.length === 0) {
-      delete modules[m];
-    }
-  }
-
-  return modules;
-}
-
-
-
 const RESOLVED_TYPES = [
   'components',
   'helpers',
@@ -177,23 +107,23 @@ function generateResolvedTypeNavigationItems(modules, type) {
 }
 
 function generateModuleNavigationItems(modules, type) {
-  let navItems = modules.reduce((navItems, m) => {
+  return modules.reduce((navItems, m) => {
     let items = m[type].map((item) => {
+      let path = item.id ? item.id : `${m.id}#${item.name}`;
+
       return {
-        path: `root/${item.id || m.id}`,
+        path: `modules/${path}`,
         name: item.name,
         isDefault: item.exportType === 'default'
       };
     });
 
     if (items.length > 0) {
-        navItems[m.file] = _.sortBy(items, ['name']);
+      navItems[m.file] = _.sortBy(items, ['name']);
     }
 
     return navItems;
   }, {});
-
-  return hoistDefaults(navItems);
 }
 
 function generateNavigationIndex(modules, klasses) {
@@ -255,7 +185,6 @@ module.exports = class DocsCompiler extends CachingWriter {
     removeHiddenDocs(modules);
     removeEmptyModules(modules);
     compileDocDescriptions(modules);
-    stripAppAddonDirs(modules);
 
     let project = {
       id: name,

tests/acceptance/sandbox/api/helpers-test.js

@@ -37,7 +37,7 @@ module('Acceptance | API | helpers', function(hooks) {
 
         assert.equal(
           helperItem.importPath,
-          `import { ${helperName} } from 'ember-cli-addon-docs/helpers/${kebabName}';`,
+          `import { ${helperName} } from 'sandbox/helpers/${kebabName}';`,
           'renders the import path correctly'
         );