Support standalone docs apps

[ef4]

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. This option is what opts you into the new behavior, otherwise nothing should be changed.

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).

[ef4]

This and the many other edits like it are because we don't want to hard-code the name "dummy" as our app's modulePrefix.

[ef4]

Now instead of a single projectPathInRepo, we have separate addonPathInRepo and docsAppPathInRepo.

[ef4]

As of ember-animation/ember-animated#171 ember-animated is using this fork, so you can see how it works. It's deployed as https://ember-animation.github.io/ember-animated/versions/master/

[samselikoff]

Amazing amount of effort + work. Thanks for donating so much to this community project!

Could you give us a tl;dr of the steps an Addon should/would take to move from the dummy app to a standalone /docs app?

[ef4]

General steps to convert an existing dummy app to a separate app:

1. Decide whether you want a monorepo or a nested app. Either should work, but they have different pros and cons. With a monorepo you only need to run yarn install once and you get efficient sharing of dependencies. But it's also harder for users to point their app directly at an unreleased commit or fork of your addon.

   In my case, I went with a nested app, meaning I have a regular ember-addon, plus a /docs folder that contains a regular ember app. So you need to yarn install in both before the docs app will work.

2. Generate a new app to be your docs app, with ember new. ember-cli doesn't like to generate new apps inside existing apps, so you may need to generate it elsewhere first and then move it into place.

3. Make your docs app depend on your addon. In my case, I did it as an in repo addon. If you're using a monorepo with yarn workspaces, you can have a regular devDependency on it instead.

4. Add ember-cli-addon-docs to your docs app.

5. Configure the docs app's ember-cli-build.js to tell ember-cli-addon-docs to point at the addon:

   let app = new EmberApp(defaults, {
     'ember-cli-addon-docs': {
       documentingAddonAt: '..'
     }
   });

   At this point you should be able to run the docs app and it should look the same as if you had just added ember-cli-addon-docs for the first time to your addon.

6. Move all the things (routes, templates, components, styles, etc) in your tests/dummy app into your new docs app. Also move any tests that are specifically about testing the docs app, as opposed to testing the addon. When you're done, you'll still have a dummy app and you can still use it for dev and test, but it won't contain the docs.

7. Remember to configure CI to run ember test in both the addon and the docs app.

8. If you have a nested docs app, remember to configure .npmignore or equivalent so you don't publish the whole docs app to NPM.

[samselikoff]

@ef4 any idea if Dependabot will work with both the root addon and the app in a subdirectory?

[ef4]

I think dependabot lets you configure individual directories in a repo, but somebody should try it.

[RobbieTheWagner]

@samselikoff are we good to merge this?

[samselikoff]

I think it would be fine to merge but also would be good to get one other app testing it? Ideally even a test-project within this repo but if that's too much work just convert some other Addon to use a separate project.

[josemarluedke]

I started working on a new set of addons and created an app for the docs. I tested this branch with my setup and it is working as expected. It would be awesome to get this merged into master and released.

My setup is here: https://github.com/josemarluedke/frontile/tree/docs-app

[RobbieTheWagner]

@samselikoff is that good enough to merge?

[samselikoff]

Seems good! Will try to do this on one of my addons soon.