Project layout, usage, testing preset placeholders

docs/SUMMARY.md

@@ -3,6 +3,7 @@
 * [Introduction](/README.md)
 * [Installation](/installation.md)
 * [Usage](/usage.md)
+* [Project Layout](/project-layout.md)
 * [Presets](/presets/README.md)
   * [Web Preset](/presets/neutrino-preset-web/README.md)
   * [React Preset](/presets/neutrino-preset-react/README.md)

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

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

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

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

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

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

docs/project-layout.md

@@ -0,0 +1,39 @@
+# Project Layout
+
+Out of the box Neutrino presets expect a project to have a particular structure in order to make the
+development process for new projects as quick as possible. This is broken up into three directories:
+
+- Source code
+- Build assets
+- Testing
+
+Each of these directories are set up via convention by a Neutrino preset, but echo can be customized as
+desired by overriding the preset's configuration or using a different preset. See
+[Custom Configuration](#) for detailed instructions.
+
+## Source Code
+
+By default Neutrino presets expect all project source code to live in a directory named `src` in the
+root of the project. This includes JavaScript files, CSS stylesheets, images, and any other assets
+that would be available to your compiled project.
+
+When running your project or creating a build bundle, Neutrino will look for this `src` directory for
+the entry point(s) to your application and use this as the relative location for finding other assets
+necessary for creating your builds.
+
+## Build Assets
+
+When creating a build bundle, Neutrino presets will put the compiled assets, including any generated
+JavaScript files, into a directory named `build` by default. Typically your Neutrino preset will copy
+any non-JavaScript files from the source directory over to the build directory, allowing you to maintain
+the same relative path structure for static assets as is used for the built assets.
+
+Normally most projects will exclude checking in this build directory to source control, e.g. git, hg, etc.
+Be sure to add this directory to your project's `.gitignore`, `.hgignore`, or similar file.
+
+## Testing
+
+Neutrino presets expect all tests to be located in a directory named `test`. In order to make the
+separation between tests and test fixtures or harnesses easier to differentiate, Neutrino presets also
+usually look for test files ending in `_test.js` or `.test.js`. See your specific test preset for more
+detailed information about running tests and other conventions.

docs/usage.md

@@ -15,22 +15,22 @@ In a typical project:
 - `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
+typical recommendations for script target names, you may choose a different name if desired
 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`
+which is available in your project source code. Depending on the presets you are using, `neutrino start`
 may also spin up a development server with hot module reloading capabilities.
-Check your preset for details.
+Check the documentation of 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
+neutrino start --presets PRESET_MODULE
 ```
 
 Putting this into your `package.json` will allow you to build your project using either
@@ -48,30 +48,78 @@ Putting this into your `package.json` will allow you to build your project using
 
 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.
+which is available in your project source code. See the documentation for your preset for details regarding additional
+steps after your build is completed.
 
 ```bash
 # PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react
-neutrino build --preset PRESET_MODULE
+neutrino build --presets 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:
+`yarn build` or `npm run build`. Using `neutrino-preset-react` as an example:
 
 ```json
 {
   "scripts": {
-    "start": "neutrino build --preset neutrino-preset-react"
+    "build": "neutrino build --presets neutrino-preset-react"
   }
 }
 ```
 
 ## Building and running tests
 
-Neutrino provides the command `neutrino test` for creating a production bundle for use in executing tests.
+Neutrino provides the command `neutrino test` for invoking a set of tests included in your project.
 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.
+variable, which is available in your project source code. How your source code is built and consumed from tests
+is determined by the preset your are using. Running suites that are built the same as source files are encouraged
+to use a Neutrino-compatible preset. Neutrino currently provides three core testing presets: Karma, Jest, and Mocha.
+
+```bash
+# PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react
+# TESTING_MODULE is the name of another preset to build with, e.g. neutrino-preset-karma
+neutrino build --presets PRESET_MODULE TESTING_MODULE
+```
+
+Putting this into your `package.json` will allow you to test your project using either
+`yarn test` or `npm test`. Using `neutrino-preset-react` and `neutrino-preset-karma` as an example:
 
+```json
+{
+  "scripts": {
+    "test": "neutrino test --presets neutrino-preset-react neutrino-preset-karma"
+  }
+}
+```
 
+Using the command `neutrino test` will execute every test file located in your
+[testing directory](/project-layout#Testing). You may also provide to this command the specific test files you wish
+to run individually. It is important to note that when combined with the `--presets` parameter, you should use two
+dashes after the last preset to denote the end of the presets and the beginning of the test files.
 
-## Default project layout
+```bash
+neutrino build --presets PRESET_A PRESET_B -- a_test.js b_test.js
+```
+
+## Using multiple presets
+
+All Neutrino commands support the `--presets` command line parameter, but having to specify this for each script target
+can be cumbersome, especially if you have many presets. Fortunately Neutrino also supports specifying presets using the
+`config.presets` field in your project's package.json file. By omitting the `--presets` flag and specifying a
+`config.presets` array, every call to a Neutrino command will look up which presets are configured in your package.json.
+
+```json
+{
+  "config": {
+    "presets": [
+      "neutrino-preset-react",
+      "neutrino-preset-karma"
+    ]
+  },
+  "scripts": {
+    "start": "neutrino start",
+    "build": "neutrino build",
+    "test": "neutrino test"
+  }
+}
+```