add some examples of app/addon/engine usage

packages/ember-cli-eyeglass/README.md

@@ -5,7 +5,7 @@ eyeglass support via node-sass.
 
 ## Installation
 
-`npm install --save-dev ember-cli-eyeglass`
+`yarn add ember-cli-eyeglass`
 
 Then rename all your `.css` files so they have the `.scss` extension.
 
@@ -22,21 +22,94 @@ options documentation](https://github.com/sass-eyeglass/broccoli-eyeglass#option
 // path/to/app/ember-cli-build.js
 const app = new EmberApp(defaults, {
   eyeglass: {
-    /* broccoli-eyeglass options */
-    /* node-sass options */
+    /* Enable discovery of Sass files to compile.
+       All files not beginning with an underscore will be compiled. */
+    discover: true,
+     /* apply other broccoli-eyeglass options here */
+     /* apply node-sass options here */
     eyeglass: {
       /* eyeglass options */
     }
   }
 });
 ```
 
+Given the following layout:
+
+```sh
+app/styles/app.scss
+           other.scss
+           _shared.scss
+```
+
+
+Will result in:
+
+`assets/<app-name>.css` containing the compiled output of `app/styles/app.scss`
+`assets/foo.css` containing the compiled output of `app/styles/foo.scss`
+
+The contents of `app/styles/_shared.scss` will not be compiled directly but will be available for import. For example, `app.scss` can have `@import "shared";` to include the contents of that file in its output.
+(Note: files beginning with an underscore are called *partials* in Sass's documentation.)
+
+
+### Addons
+
+To make an ember-addon (both in-repo and from node_modules) behave as an eyeglass module, add `"eyeglass-module"` to the `package.json`'s `"keywords"` array and add the [relevant config](https://github.com/linkedin/eyeglass/tree/master/packages/eyeglass#writing-an-eyeglass-module) to the `"eyeglass"` property in `package.json`. To compile the addon's styles from `addon/styles` using eyeglass, add `ember-cli-eyeglass` as a dependency of the addon in question.
+
+ember-addons have two important directories, `app` and `addon`:
+
+#### my-addon/app/styles
+
+These assets are only considered for top-level addons, stylesheets in `app` directories of nested-addons are ignored.
+
+Given the following folder structure:
+
+```sh
+my-addon/app/styles/
+                   /my-addon.scss
+                   /my-other-file.scss
+                   /_a-partial.scss
+
+```
+
+* `my-addon/app/styles` - The non-partial `scss` files will become independent css files in the built output.
+* `my-addon/addon/styles` - The non-partial `scss` files will be compiled and the output merged into your application's `vendor.css`;
+
+
+Will result in:
+
+`assets/my-addon.css` containing the compiled output of `my-addon/app/styles/my-addon.scss`
+`assets/my-other-file.css` containing the compiled output of `my-addon/app/styles/my-other-file.scss`
+`_a-partial.scss` will not be included by default, unless the files in `my-app/app/styles/` or `my-addon/app/styles` import it.
+
+
+
+#### my-addon/addon/styles/
+
+These assets merged namespaced by the current addons name for all addons.
+
+Given the following folder structure:
+
+```sh
+my-addon/addon/styles/
+                     /_shared.scss
+                     /my-addon.scss
+                     /secondary.scss             
+```
+
+The contents of `my-addon/addon/styles/my-addon.scss` will be added to `assets/vendor.css`.
+The contents of `my-addon/addon/styles/secondary.scss` will be added to `assets/vendor.css`.
+The contents of `my-addon/addon/styles/_shared.scss` will only be included if `my-addon.scss` or `secondary.scss` explicitly import them.
+
 ### Engines
 
+Engines are enhanced addons, who optionally (if lazy) provide alternative `app` and `vendor` output.
+
 ```js
 // path/to/engine/index.js
 const app = new EmberEngine(defaults, {
   eyeglass: {
+    discover: true,
     /* broccoli-eyeglass options */
     /* node-sass options */
     eyeglass: {
@@ -45,6 +118,43 @@ const app = new EmberEngine(defaults, {
   }
 });
 ```
+
+Given the following folder structure:
+
+```sh
+
+my-engine/
+         /app/styles/
+                    /my-engine.scss
+                    /my-other-file.scss
+                    /_shared.scss
+         /addon/styles/
+                      /_shared.scss
+                      /my-engine.scss
+                      /secondary.scss             
+```
+
+If this is an eager engine:
+
+
+The contents of `my-engine/app/styles/my-engine.scss` will become `dist/assets/eager.css`
+The contents of `my-engine/app/styles/my-other-file.scss` will become `dist/assets/my-other-file.css`
+The contents of `my-engine/app/styles/_shared.scss` will only be included if `my-engine.scss` or `my-other-file.scss` explicitly import them.
+
+The contents of `my-engine/addon/styles/my-addon.scss` will be added to `dist/assets/vendor.css`
+The contents of `my-engine/addon/styles/secondary.scss` will be added to `dist/assets/vendor.css`
+The contents of `my-engine/addon/styles/_shared.scss` will only be included if `my-addon.scss` or `secondary.scss` explicitly import them.
+
+If this is a lazy engine:
+
+The contents of `my-engine/app/styles/my-engine.scss` will become ???
+The contents of `my-engine/app/styles/my-other-file.scss` will become ???
+The contents of `my-engine/app/styles/_shared.scss` will become ???
+
+The contents of `my-engine/addon/styles/my-addon.scss` will be added to `dist/engine-dist/my-engine/assets/engine.css`
+The contents of `my-engine/addon/styles/secondary.scss` will be added to `dist/engine-dist/my-engine/assets/engine.css`
+The contents of `my-engine/addon/styles/_shared.scss` will only be included if `my-addon.scss` or `secondary.scss` explicitly import them.
+
 
 ## Building