docs: Documentation!

Author: bendemboski

blueprints/ember-electron/index.js

@@ -14,7 +14,7 @@ const writeFile = denodeify(fs.writeFile);
 const YAWN = require('yawn-yaml/cjs');
 const SilentError = require('silent-error');
 const {
-  upgradeUrl,
+  upgradingUrl,
   ciUrl
 } = require('../../lib/utils/documentation-urls');
 
@@ -44,7 +44,7 @@ module.exports = class EmberElectronBlueprint extends Blueprint {
       this.ui.writeLine(chalk.yellow([
         `\n'ember-electron' directory detected -- this looks like an ember-electron`,
         `v2 project. Setting up an updated project will not be destructive, but you`,
-        `should read the upgrade documentation at ${upgradeUrl}.\n`
+        `should read the upgrading documentation at ${upgradingUrl}.\n`
       ].join(' ')));
     }
   }

lib/commands/base.js

@@ -8,7 +8,7 @@ const YarnOrNpmTask = require('../tasks/yarn-or-npm');
 const Win = require('ember-cli/lib/utilities/windows-admin');
 const fs = require('fs');
 const { electronProjectPath } = require('../utils/build-paths');
-const { upgradeUrl } = require('../utils/documentation-urls');
+const { upgradingUrl } = require('../utils/documentation-urls');
 const SilentError = require('silent-error');
 
 module.exports = Command.extend({
@@ -30,7 +30,7 @@ module.exports = Command.extend({
           `contain an electron-forge project. It should have been generated by`,
           `ember-electron's blueprint when you first ran 'ember install`,
           `ember-electron'. If you are upgrading from ember-electron v2, you`,
-          `should read the upgrade documentation at ${upgradeUrl}.`,
+          `should read the upgrading documentation at ${upgradingUrl}.`,
         ].join(' '))
       );
     }

lib/utils/documentation-urls.js

@@ -1,9 +1,9 @@
 const baseUrl = 'https://adopted-ember-addons.github.io/ember-electron/docs/';
 const guidesUrl = `${baseUrl}guides/`;
-const upgradeUrl = `${guidesUrl}upgrade`;
+const upgradingUrl = `${guidesUrl}upgrading`;
 const ciUrl = `${guidesUrl}ci`;
 
 module.exports = {
-  upgradeUrl,
+  upgradingUrl,
   ciUrl
 };

tests/dummy/app/router.js

@@ -11,18 +11,16 @@ Router.map(function() {
     this.route('faq', function() {
       this.route('common-issues');
       this.route('security');
-      this.route('structure');
-      this.route('test-runner-deprecation');
     });
 
     this.route('guides', function() {
-      this.route('build-pipeline');
       this.route('ci');
-      this.route('configuration');
+      this.route('common-issues');
+      this.route('development-and-debugging');
       this.route('installation');
-      this.route('packaging');
-      this.route('testing');
-      this.route('upgrade');
+      this.route('security');
+      this.route('structure');
+      this.route('upgrading');
       this.route('usage');
     });
   });

tests/dummy/app/templates/docs.hbs

@@ -5,18 +5,14 @@
     {{nav.section "Guides"}}
     {{nav.item "Installation" "docs.guides.installation"}}
     {{nav.item "Usage" "docs.guides.usage"}}
-    {{nav.item "Configuration" "docs.guides.configuration"}}
-    {{nav.item "Packaging" "docs.guides.packaging"}}
-    {{nav.item "Testing" "docs.guides.testing"}}
-    {{nav.item "Upgrade" "docs.guides.upgrade"}}
+    {{nav.item "Structure" "docs.guides.structure"}}
+    {{nav.item "Upgrading" "docs.guides.upgrading"}}
+    {{nav.item "Development and Debugging" "docs.guides.development-and-debugging"}}
     {{nav.item "CI" "docs.guides.ci"}}
-    {{nav.item "Build Pipeline" "docs.guides.build-pipeline"}}
 
     {{nav.section "FAQ"}}
     {{nav.item "Common Issues" "docs.faq.common-issues"}}
     {{nav.item "Security" "docs.faq.security"}}
-    {{nav.item "Structure" "docs.faq.structure"}}
-    {{nav.item "Test Runner Deprecation" "docs.faq.test-runner-deprecation"}}
   {{/viewer.nav}}
 
   {{#viewer.main}}

tests/dummy/app/templates/docs/faq/common-issues.md

@@ -44,12 +44,3 @@ In your ember-electron/main.js file, find the `BrowserWindow` that is being used
 const myWindow = new BrowserWindow({});
 myWindow.webContents.openDevTools();
 ```
-
-
-## `ember-welcome-page` does not show in production mode
-
-If you try out Ember-Electron for the first time on a brand new Ember project generated with `ember init`, you may find that the welcome page you see when running `ember electron` does no longer show up when you run an application packaged with `ember electron:package`.
-
-While this might be a little confusing, it is the default behavior of the `ember-welcome-page` addon, which simply removes itself when run with the environment flag `--env=production`, which is our default while packaging applications.
-
-Since you probably don't need that page anyway, you can safely follow it's own instructions and remove it from your `package.json` as well as the template tag `{{welcome-page}}` from your `app/templates/application.hbs`.

tests/dummy/app/templates/docs/faq/security.md

@@ -43,3 +43,20 @@ and the MDN [Web security landing page](https://developer.mozilla.org/en-US/docs
   e.g. `Refused to load...because it violates the following Content Security Policy directive:...`
 * If there are no problems then you are done.
   Otherwise, you'll need to examine the code in violation and either make it compliant or adjust the policy to allow it.  
+
+## Why do I see "Electron Security Warning (Insecure Resources)" when running tests?
+
+To aid users in keeping their applications secure, Electron warns about any scripts
+or other resources loaded out of `index.html` without encryption (using `http:`
+rather than `https:`). When running tests, the renderer process has to load some
+resources from the local express server to allow it to communicate with testem, which
+manages the test run, and this cannot easily be done over `https:`. The expected list
+of URLs is:
+
+```
+- http://testemserver/testem.js
+- http://testemserver/testem/connection.html
+```
+
+We leave the security warnings enabled when running tests so you can see if it's warning
+about any other insecure content, besides the URLs listed about, loaded during tests.

tests/dummy/app/templates/docs/faq/structure.md

@@ -4,28 +4,18 @@ You can test your application using Electron with the `ember electron:test` comm
 
  * Install [`xvfb`](https://en.wikipedia.org/wiki/Xvfb). It's a virtual framebuffer, implementing the X11 display server protocol - it performs all graphical operations in memory without showing any screen output, which is exactly what we need. A [Jenkins addon is available](https://wiki.jenkins-ci.org/display/JENKINS/Xvfb+Plugin).
  * Create a virtual `xvfb` screen and export an environment variable called `DISPLAY` that points to it. Electron will automatically pick it up.
- * Install a recent C++ compiler (e.g. gcc). This is to enable the CI server to build native modules for Node.js.
- * Finally, ensure that `npm test` actually calls `ember electron:test`. You can configure what command `npm test executes` by changing it in your `package.json`.
+ * Finally, ensure that `npm test` or `yarn test` actually calls `ember electron:test`. You can configure what command `npm test executes` by changing it in your `package.json`.
 
-On Travis, the configuration should look like this:
+When you first install `ember-electron`, the blueprint will update your .travis.yml, but if it fails or you need to do it manually for some reason, your configuration should include the following:
 
 ```yaml
-env:
-  - CXX=g++-4.8
-
 addons:
   apt:
-    sources:
-      - ubuntu-toolchain-r-test
     packages:
       - xvfb
-      - g++-4.8
-
-before_install:
-  - "npm config set spin false"
 
 install:
-  - npm install
+  - <npm or yarn install>
   - export DISPLAY=':99.0'
   - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
 ```