Moar docs

.gitignore

@@ -43,3 +43,6 @@ jspm_packages
 
 # Webstorm project metadata
 .idea
+
+# Gitbook docs
+_book

.scripts/publish-all

@@ -1,30 +0,0 @@
-#! /usr/bin/env node
-
-const { readdirSync, writeFileSync } = require('fs');
-const { resolve, join } = require('path');
-const { execSync } = require('child_process');
-const clone = require('lodash.clonedeep');
-
-function writeJson(destination, content) {
-  writeFileSync(destination, `${JSON.stringify(content, null, 2)}\n`);
-}
-
-const packages = resolve(__dirname, '../packages');
-
-readdirSync(packages)
-  .map(name => {
-    const dir = join(packages, name);
-    const pkgPath = join(dir, 'package.json');
-    const pkg = require(pkgPath);
-    const original = clone(pkg);
-
-    Object
-      .keys(pkg.linkDependencies || {})
-      .map(key => {
-        pkg.dependencies[key] = pkg.linkDependencies[key];
-      });
-
-    writeJson(pkgPath, pkg);
-    execSync(`yarn publish ${dir}`, { stdio: 'inherit' });
-    writeJson(pkgPath, original);
-  });

README.md

@@ -1,8 +1,6 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/logo.png" height="100" />
-</p>
+# <a href="http://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/logo.png" height="60"></a>
 
-<p align="center">Create and build modern JavaScript applications with zero initial configuration.</p>
+Create and build modern JavaScript applications with zero initial configuration.
 
 ---
 
@@ -13,7 +11,7 @@ presets or configurations. It intends to make the process of initializing and bu
 much simpler by providing minimal development dependencies. Neutrino uses Webpack to build both
 web and Node.js projects by providing complete build presets which can be shared across targets and
 projects. You can use Neutrino base presets to get started building a variety of projects, create your
-own presets by extending the Neeutrino core presets to be shared across your own projects or even by the
+own presets by extending the Neutrino core presets to be shared across your own projects or even by the
 community. Presets can even be manipulated on a project-by-project basis to handle almost any build
 situation your preset doesn't cover.
 

docs/README.md

@@ -1,3 +1,11 @@
-# Table of Contents
+# <a href="http://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/logo.png" height="60"></a>
 
-* [Readme](/README.md)
+### Create and build modern JavaScript applications with zero initial configuration
+#### Think: Webpack, but with presets. That's Neutrino.
+
+---
+
+Neutrino is a companion tool which lets you build web and Node.js applications with shared presets or configurations. It intends to make the process of initializing and building projects much simpler by providing minimal development dependencies.
+
+Neutrino uses Webpack to build both web and Node.js projects by providing complete build presets which can be shared across targets and projects. You can use Neutrino base presets to get started building a variety of projects, create your
+own presets by extending the Neutrino core ones to be shared across your own projects or even by the community. Presets can even be manipulated on a project-by-project basis to handle almost any build situation your preset doesn't cover.

docs/SUMMARY.md

@@ -0,0 +1,12 @@
+# Summary
+
+* [Introduction](/README.md)
+* [Installation](/installation.md)
+* [Usage](/usage.md)
+* [Presets](/presets/README.md)
+  * [Web Preset](/presets/neutrino-preset-web/README.md)
+  * [React Preset](/presets/neutrino-preset-react/README.md)
+  * [Node.js Preset](/presets/neutrino-preset-node/README.md)
+  * [Base Preset](/presets/neutrino-preset-base/README.md)
+  * [Overriding a preset](/presets/overriding-a-preset.md)
+  * [Creating a preset](/presets/creating-a-preset.md)

docs/installation.md

@@ -0,0 +1,38 @@
+# Installing Neutrino
+
+Installing Neutrino requires Node.js v6+, and either [Yarn](https://yarnpkg.com/lang/en/docs/install/) or
+npm. At a minimum you will be installing Neutrino and a Neutrino preset, such as `neutrino-preset-react`.
+
+### Yarn Installation
+
+Run the following command inside your project directory. Substitute `PRESET_PKG` with the name of the preset
+you wish to install.
+
+```bash
+yarn add --dev neutrino PRESET_PKG
+```
+
+For example, if you wanted to build your project using Neutrino's React preset:
+
+```bash
+yarn add --dev neutrino neutrino-preset-react
+```
+
+### npm Installation
+
+Run the following command inside your project directory. Substitute `PRESET_PKG` with the name of the preset
+you wish to install.
+
+```bash
+npm install --save-dev neutrino PRESET_PKG
+```
+
+For example, if you wanted to build your project using Neutrino's React preset:
+
+```bash
+npm install --save-dev neutrino neutrino-preset-react
+```
+
+### Getting started
+
+Please continue through the documentation for instructions on Neutrino usage and default project layout.

docs/presets/README.md

@@ -0,0 +1,39 @@
+# What are presets?
+
+A preset is a Webpack- or Neutrino-compatible configuration capable of building or modifying
+the build process for a project. Neutrino provides a few core presets to quickly get
+started building some popular project types, but anyone can inherit, extend, and modify these
+presets and tailor them to their project preferences. You can even create your own
+presets from scratch.
+
+If you are familiar with Babel presets, Neutrino presets work similarly. For example,
+given the Babel preset `babel-preset-react`, you can compile React code with JSX
+to vanilla JavaScript calls. Neutrino adopts this same concept. Many more aspects of
+development surround building a complete React project, for which Webpack is commonly used.
+By encapsulating the common needs of a project type into a preset, Neutrino allows you to
+avoid the upfront cost of configuring and instead focus on project development.
+
+Not every project is the same, and oftentimes small tweaks need to be made to the build
+configuration in order to meet this need. Fortunately Neutrino presets can be modified and
+extended directly from the project you are building. No need to be locked in to a particular
+pattern, and no escape hatches that force you into maintaining the entire configuration should
+you need to make changes.
+
+Presets can be easily distributing by publishing them to npm or GitHub and installing them
+in your project. This also allows others to discover and build projects based on your own
+presets.
+
+### Why not a boilerplate or alternative?
+
+Boilerplates are great resources for scaffolding out application-specific code which
+would be difficult or tedious to generate for every project. Unfortunately many projects
+also bake in build configuration into this process, causing a lot of duplication. If you
+need to make a change to your build steps, you are forced to make that change across all
+your similar projects. Using a preset rather than a boilerplate keeps this process DRY.
+
+Tools like [Create React App](https://github.com/facebookincubator/create-react-app) have
+been fantastic improvements to the tooling ecosystem, but unfortunately only works on specific
+environments like React, and do not allow simple extensibility of the build configuration. To
+answer this new and similar projects are cropping up to build different types of projects,
+often duplicating efforts which miss out on the best practices to share with the other project
+types.

docs/presets/neutrino-preset-base/README.md

@@ -0,0 +1 @@
+# heading

docs/presets/neutrino-preset-node/README.md

@@ -0,0 +1,5 @@
+# heading
+
+**Important Note:** At the time of writing, Neutrino's Node preset does not support `watch`
+compilation with `neutrino start`; it will instead fall back to running a build with the `NODE_ENV`
+environment variable set to `development`.

docs/presets/neutrino-preset-react/README.md

@@ -0,0 +1 @@
+# heading

docs/presets/neutrino-preset-web/README.md

@@ -0,0 +1 @@
+# heading

docs/usage.md

@@ -0,0 +1,77 @@
+# Usage
+
+Neutrino is a command-line tool that wraps Webpack in order to support building JavaScript projects
+based on shared configuration presets. You can use Neutrino within your project, preferably using
+scripts defined in your project's `package.json`.
+
+## Setup
+
+After completing the [installation](/installation.md) of Neutrino and your Neutrino preset, you will
+want to define some scripts in your project's `package.json` in order to simply build your project.
+In a typical project:
+
+- `scripts.start` would be the command you wish to run during development
+- `scripts.build` would be the command you wish to run to create a production bundle
+- `scripts.test` would be the command you wish to run to execute tests
+
+Using these script targets may not be suitable for every project; know that they are just
+typical recommendations for script target names, you may choose a different name if necessary
+for your project.
+
+## Building for development
+
+Neutrino provides the command `neutrino start` for creating a bundle during development. Using
+`neutrino start` sets the Node.js environment to `development` using the `NODE_ENV` environment variable,
+which is available in your project source code. Depending on the preset you are using, `neutrino start`
+may also spin up a development server with hot module reloading capabilities.
+Check your preset for details.
+
+Usage:
+
+```bash
+# PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react
+neutrino start --preset PRESET_MODULE
+```
+
+Putting this into your `package.json` will allow you to build your project using either
+`yarn start` or `npm start`. Using `neutrino-preset-react` as an example:
+
+```json
+{
+  "scripts": {
+    "start": "neutrino start --preset neutrino-preset-react"
+  }
+}
+```
+
+## Building for production
+
+Neutrino provides the command `neutrino build` for creating a bundle for production deployment.
+Using `neutrino build` sets the Node.js environment to `production` using the `NODE_ENV` environment variable,
+which is available in your project source code.
+
+```bash
+# PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react
+neutrino build --preset PRESET_MODULE
+```
+
+Putting this into your `package.json` will allow you to build your project using either
+`yarn start` or `npm start`. Using `neutrino-preset-react` as an example:
+
+```json
+{
+  "scripts": {
+    "start": "neutrino build --preset neutrino-preset-react"
+  }
+}
+```
+
+## Building and running tests
+
+Neutrino provides the command `neutrino test` for creating a production bundle for use in executing tests.
+Using `neutrino test` sets the Node.js environment variable to `test` using the `NODE_ENV` environment
+variable, which is available in your project source code.
+
+
+
+## Default project layout

package.json

@@ -9,15 +9,23 @@
   "license": "MPL-2.0",
   "scripts": {
     "bootstrap": "autolink bootstrap",
-    "postinstall": "autolink bootstrap",
     "clean-all": "autolink clean",
     "link-all": "autolink link",
+    "docs:build": "gitbook build",
+    "docs:deploy": "yarn docs:build && gh-pages --dist _book --remote upstream",
+    "docs:serve": "gitbook serve",
     "bump:major": ".scripts/version-all major",
     "bump:minor": ".scripts/version-all minor",
     "bump:patch": ".scripts/version-all patch",
     "publish-all": ".scripts/publish-all"
   },
   "devDependencies": {
+    "gh-pages": "^0.12.0",
+    "gitbook-cli": "^2.3.0",
+    "gitbook-plugin-anchorjs": "^1.1.1",
+    "gitbook-plugin-edit-link": "^2.0.2",
+    "gitbook-plugin-github": "^2.0.0",
+    "gitbook-plugin-prism": "^2.1.0",
     "lodash.clonedeep": "^4.5.0",
     "semver": "^5.3.0",
     "yarn-autolink": "^1.1.0"

packages/neutrino/commands/test/index.js

@@ -3,9 +3,9 @@
 const getPreset = require('../../src/get-preset');
 const Server = require('karma').Server;
 const builder = require('../build');
-const mocha = require('../../src/mocha');
+const mochaBin = require('../../src/mocha');
 
-const browser = (config, args, done) => {
+const karma = (config, args, done) => {
   const karma = config.karma;
 
   delete config.karma;
@@ -21,18 +21,19 @@ const browser = (config, args, done) => {
   new Server(karma, done).start();
 };
 
-const node = (config, args, done) => {
+const mocha = (config, args, done) => {
   args.options.watch ?
-    builder.watch(config, () => mocha(config, args), done) :
-    builder.build(config, () => mocha(config, args, done));
+    builder.watch(config, () => mochaBin(config, args), done) :
+    builder.build(config, () => mochaBin(config, args, done));
 };
 
 module.exports = (args, done) => {
   const config = getPreset(args.options.preset);
 
+
   if (config.plugins.find(p => p.options && p.options.options && p.options.options.mocha)) {
-    node(config, args, done);
+    mocha(config, args, done);
   } else {
-    browser(config, args, done);
+    karma(config, args, done);
   }
 };

packages/neutrino/package.json

@@ -9,7 +9,7 @@
   "commands": [
     {
       "command": "start",
-      "description": "Start a development server",
+      "description": "Build the project in development mode",
       "options": {
         "-p, --preset [nameOrFile]": "Specify a configuration preset for running the development server"
       }
@@ -24,7 +24,7 @@
     },
     {
       "command": "test [files...]",
-      "description": "Run a set of test suites against the configured test directory or specifid files",
+      "description": "Run a set of test suites against the configured test directory or specific files",
       "environment": "test",
       "options": {
         "-p, --preset [nameOrFile]": "Specify a configuration preset for running tests",