[feat] Document AddonDocsRouter and hooks

 ◇
 ◇ This feature snuck in in #173 but we'd talked about it before.
 ◇ Providing our own router class means we can control it and
 ◇ add things, like the RouterScroll mixin or didTransition hooks
 ◇ (which is why I added it in an experiment in #173). The
 ◇ docsRoute function sets up all the docs routes correctly,
 ◇ and allows us to maintain control over them in case we want to
 ◇ make more changes in the future.
 ◇
 ◇ I think ideally we would copy the new router file directly,
possibly by the blueprint, but I'm not sure that step can be
fully automated (existing routes and such) so I updated the guides
and docs here

Author: pzuraq

addon/components/api/x-sections/template.hbs

@@ -9,7 +9,7 @@
         <div data-test-item>
           {{#if (or item.isClass item.isComponent)}}
             <h3 id={{item.name}} data-test-item-header class="item-section__class-header mb-1">
-              {{#link-to 'docs.api.item' (concat 'root/' item.id)}}
+              {{#link-to 'docs.api.item' (concat 'modules/' item.id)}}
                 {{#if (eq item.exportType 'default')}}
                   <span class="item-section__default-label">Default</span>
                 {{/if}}

addon/router.js

@@ -1,8 +1,43 @@
+/** @documenter yuidoc */
+
 import EmberRouter from '@ember/routing/router';
 import RouterScroll from 'ember-router-scroll';
 
+/**
+  The AddonDocsRouter, which adds some extra functionality. This should be used
+  instead of the standard EmberRouter class in your docs app.
+
+  ```js
+  import AddonDocsRouter, { docsRoute } from 'ember-cli-addon-docs/router';
+  import config from './config/environment';
+
+  const Router = AddonDocsRouter.extend({
+    location: config.locationType,
+    rootURL: config.rootURL,
+  });
+  ```
+
+  @class AddonDocsRouter
+  @extends EmberRouter
+*/
 export default EmberRouter.extend(RouterScroll);
 
+/**
+  Creates the docs route and api docs routes. Can receive a callback with the
+  routes you want to add to your docs.
+
+  ```js
+  import AddonDocsRouter, { docsRoute } from 'ember-cli-addon-docs/router';
+
+  Router.map(function() {
+    docsRoute(this, function() {
+      this.route('usage');
+    });
+  });
+  ```
+
+  @function docsRoute
+*/
 export function docsRoute(router, callback) {
   router.route('docs', function() {
     callback.apply(this);

tests/dummy/app/pods/docs/quickstart/template.md

@@ -11,16 +11,23 @@ marketing/demo page you can use to promote your addon.
   ember install ember-cli-addon-docs
   ```
 
-2. **Add the docs routes.** Open `tests/dummy/app/router.js` and add the
-following route definitions to your main route.
+2. **Add the docs routes.** Open `tests/dummy/app/router.js` and replace the
+standard EmberRouter with the AddonDocsRouter:
 
   {{#docs-snippet name='quickstart-router.js' title='tests/dummy/app/router.js'}}
-    this.route('docs', function() { // docs homepage (required)
-      this.route('usage'); // docs subpage
-      this.route('api', function() { // autogenerated API homepage (required)
-        this.route('item', { path: '/*path' }); // autogenerated API subpages (required)
-      });
+    import AddonDocsRouter, { docsRoute } from 'ember-cli-addon-docs/router';
+    import config from './config/environment';
+
+    const Router = AddonDocsRouter.extend({
+      location: config.locationType,
+      rootURL: config.rootURL,
+    });
+
+    Router.map(function() {
+      docsRoute(this, function() { /* Your docs routes go here */ });
     });
+
+    export default Router;
   {{/docs-snippet}}
 
 3. **Create your docs skeleton.** Create a new template for the `docs` route