docs: move documentation from readme to docs

Brocco · MRHarrison · commit 75ce12f96816 · 2017-02-08T16:05:44.000-08:00
Close angular#4190
diff --git a/.editorconfig b/.editorconfig
@@ -11,4 +11,4 @@ trim_trailing_whitespace = true
 
 [*.md]
 insert_final_newline = false
-trim_trailing_whitespace = false
+trim_trailing_whitespace = true
diff --git a/README.md b/README.md
@@ -122,12 +122,12 @@ The CLI supports routing in several ways:
 - When you generate a module, you can use the `--routing` option like `ng g module my-module --routing`  to create a separate file `my-module-routing.module.ts` to store the module routes.
 
   The file includes an empty `Routes` object that you can fill with routes to different components and/or modules.
-  
+
   The `--routing` option also generates a default component with the same name as the module.
 
 - You can use the `--routing` option with `ng new` or `ng init` to create a `app-routing.module.ts` file when you create or initialize a project.
 
-
+<!-- DeleteSection1 Start here to remove upon next release -->
 ### Creating a build
 
 ```bash
@@ -276,6 +276,9 @@ This will use the `lint` npm script that in generated projects uses `tslint`.
 
 You can modify the these scripts in `package.json` to run whatever tool you prefer.
 
+<!-- DeleteSection1 End here -->
+
+ <!-- consider removing autocompletion from readme -->
 ### Commands autocompletion
 
 To turn on auto completion use the following commands:
@@ -308,6 +311,7 @@ You use the `assets` array in `angular-cli.json` to list files or folders you wa
 ]
 ```
 
+<!-- DeleteSection2 Start here to remove upon next release -->
 ### Global styles
 
 The `styles.css` file allows users to add global styles and supports
@@ -418,6 +422,8 @@ Finally add the Bootstrap CSS to the `apps[0].styles` array:
 Restart `ng serve` if you're running it, and Bootstrap 4 should be working on
 your app.
 
+<!-- DeleteSection2 End here -->
+
 ### Updating angular-cli
 
 To update `angular-cli` to a new version, you must update both the global package and your project's local package.
diff --git a/docs/documentation/build.md b/docs/documentation/build.md
@@ -5,27 +5,74 @@
 ## Overview
 `ng build` compiles the application into an output directory
 
-## Options
-`--target` (`-t`) define the build target
+### Creating a build
 
-`--environment` (`-e`) defines the build environment
+```bash
+ng build
+```
 
-`--prod` flag to set build target and environment to production
+The build artifacts will be stored in the `dist/` directory.
 
-`--dev` flag to set build target and environment to development
+### Build Targets and Environment Files
+
+`ng build` can specify both a build target (`--target=production` or `--target=development`) and an
+environment file to be used with that build (`--environment=dev` or `--environment=prod`).
+By default, the development build target and environment are used.
+
+The mapping used to determine which environment file is used can be found in `angular-cli.json`:
+
+```json
+"environments": {
+  "source": "environments/environment.ts",
+  "dev": "environments/environment.ts",
+  "prod": "environments/environment.prod.ts"
+}
+```
+
+These options also apply to the serve command. If you do not pass a value for `environment`,
+it will default to `dev` for `development` and `prod` for `production`.
 
 ```bash
 # these are equivalent
---target=production --environment=prod
---prod --env=prod
---prod
+ng build --target=production --environment=prod
+ng build --prod --env=prod
+ng build --prod
 # and so are these
---target=development --environment=dev
---dev --e=dev
---dev
+ng build --target=development --environment=dev
+ng build --dev --e=dev
+ng build --dev
 ng build
 ```
 
+You can also add your own env files other than `dev` and `prod` by doing the following:
+- create a `src/environments/environment.NAME.ts`
+- add `{ "NAME": 'src/environments/environment.NAME.ts' }` to the `apps[0].environments` object in `angular-cli.json`
+- use them via the `--env=NAME` flag on the build/serve commands.
+
+### Base tag handling in index.html
+
+When building you can modify base tag (`<base href="/">`) in your index.html with `--base-href your-url` option.
+
+```bash
+# Sets base tag href to /myUrl/ in your index.html
+ng build --base-href /myUrl/
+ng build --bh /myUrl/
+```
+
+### Bundling
+
+All builds make use of bundling, and using the `--prod` flag in  `ng build --prod`
+or `ng serve --prod` will also make use of uglifying and tree-shaking functionality.
+
+## Options
+`--target` (`-t`) define the build target
+
+`--environment` (`-e`) defines the build environment
+
+`--prod` flag to set build target and environment to production
+
+`--dev` flag to set build target and environment to development
+
 `--output-path` (`-o`) path where output will be placed
 
 `--output-hashing` define the output filename cache-busting hashing mode
diff --git a/docs/documentation/e2e.md b/docs/documentation/e2e.md
@@ -4,3 +4,13 @@
 
 ## Overview
 `ng e2e` executes end-to-end tests
+
+### Running end-to-end tests
+
+```bash
+ng e2e
+```
+
+Before running the tests make sure you are serving the app via `ng serve`.
+
+End-to-end tests are run via [Protractor](https://angular.github.io/protractor/).
diff --git a/docs/documentation/lint.md b/docs/documentation/lint.md
@@ -0,0 +1,8 @@
+# ng lint
+
+## Overview
+`ng lint` will lint your app code.
+
+This will use the `lint` npm script that in generated projects uses `tslint`.
+
+You can modify the these scripts in `package.json` to run whatever tool you prefer.
diff --git a/docs/documentation/stories/css-preprocessors.md b/docs/documentation/stories/css-preprocessors.md
@@ -0,0 +1,32 @@
+# CSS Preprocessor integration
+
+Angular-CLI supports all major CSS preprocessors:
+- sass/scss ([http://sass-lang.com/](http://sass-lang.com/))
+- less ([http://lesscss.org/](http://lesscss.org/))
+- stylus ([http://stylus-lang.com/](http://stylus-lang.com/))
+
+To use these preprocessors simply add the file to your component's `styleUrls`:
+
+```javascript
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.scss']
+})
+export class AppComponent {
+  title = 'app works!';
+}
+```
+
+When generating a new project you can also define which extension you want for
+style files:
+
+```bash
+ng new sassy-project --style=sass
+```
+
+Or set the default style on an existing project:
+
+```bash
+ng set defaults.styleExt scss
+```
diff --git a/docs/documentation/stories/deploy-github-pages.md b/docs/documentation/stories/deploy-github-pages.md
@@ -0,0 +1,30 @@
+# Deploying the app via GitHub Pages
+
+You can deploy your apps quickly via:
+
+```bash
+ng github-pages:deploy --message "Optional commit message"
+```
+
+This will do the following:
+
+- creates GitHub repo for the current project if one doesn't exist
+- rebuilds the app in production mode at the current `HEAD`
+- creates a local `gh-pages` branch if one doesn't exist
+- moves your app to the `gh-pages` branch and creates a commit
+- edit the base tag in index.html to support GitHub Pages
+- pushes the `gh-pages` branch to GitHub
+- returns back to the original `HEAD`
+
+Creating the repo requires a token from GitHub, and the remaining functionality
+relies on ssh authentication for all git operations that communicate with github.com.
+To simplify the authentication, be sure to [setup your ssh keys](https://help.github.com/articles/generating-ssh-keys/).
+
+If you are deploying a [user or organization page](https://help.github.com/articles/user-organization-and-project-pages/), you can instead use the following command:
+
+```bash
+ng github-pages:deploy --user-page --message "Optional commit message"
+```
+
+This command pushes the app to the `master` branch on the GitHub repo instead
+of pushing to `gh-pages`, since user and organization pages require this.
diff --git a/docs/documentation/stories/global-lib.md b/docs/documentation/stories/global-lib.md
@@ -0,0 +1,35 @@
+# Global Library Installation
+
+Some javascript libraries need to be added to the global scope, and loaded as if
+they were in a script tag. We can do this using the `apps[0].scripts` and
+`apps[0].styles` properties of `angular-cli.json`.
+
+As an example, to use [Bootstrap 4](http://v4-alpha.getbootstrap.com/) this is
+what you need to do:
+
+First install Bootstrap from `npm`:
+
+```bash
+npm install bootstrap@next
+```
+
+Then add the needed script files to `apps[0].scripts`:
+
+```json
+"scripts": [
+  "../node_modules/jquery/dist/jquery.js",
+  "../node_modules/tether/dist/js/tether.js",
+  "../node_modules/bootstrap/dist/js/bootstrap.js"
+],
+```
+
+Finally add the Bootstrap CSS to the `apps[0].styles` array:
+```json
+"styles": [
+  "../node_modules/bootstrap/dist/css/bootstrap.css",
+  "styles.css"
+],
+```
+
+Restart `ng serve` if you're running it, and Bootstrap 4 should be working on
+your app.
diff --git a/docs/documentation/stories/global-styles.md b/docs/documentation/stories/global-styles.md
@@ -0,0 +1,9 @@
+# Global styles
+
+The `styles.css` file allows users to add global styles and supports
+[CSS imports](https://developer.mozilla.org/en/docs/Web/CSS/@import).
+
+If the project is created with the `--style=sass` option, this will be a `.sass`
+file instead, and the same applies to `scss/less/styl`.
+
+You can add more global styles via the `apps[0].styles` property in `angular-cli.json`.
diff --git a/docs/documentation/stories/proxy.md b/docs/documentation/stories/proxy.md
@@ -0,0 +1,28 @@
+# Proxy To Backend
+
+Using the proxying support in webpack's dev server we can highjack certain urls and send them to a backend server.
+We do this by passing a file to `--proxy-config`
+
+Say we have a server running on `http://localhost:3000/api` and we want all calls to `http://localhost:4200/api` to go to that server.
+
+We create a file next to projects `package.json` called `proxy.conf.json`
+with the content
+
+```json
+{
+  "/api": {
+    "target": "http://localhost:3000",
+    "secure": false
+  }
+}
+```
+
+You can read more about what options are available here [webpack-dev-server proxy settings](https://webpack.github.io/docs/webpack-dev-server.html#proxy)
+
+and then we edit the `package.json` file's start script to be
+
+```json
+"start": "ng serve --proxy-config proxy.conf.json",
+```
+
+now run it with `npm start`
diff --git a/docs/documentation/stories/third-party-lib.md b/docs/documentation/stories/third-party-lib.md
@@ -0,0 +1,30 @@
+# 3rd Party Library Installation
+
+Simply install your library via `npm install lib-name --save` and import it in your code.
+
+If the library does not include typings, you can install them using npm:
+
+```bash
+npm install d3 --save
+npm install @types/d3 --save-dev
+```
+
+If the library doesn't have typings available at `@types/`, you can still use it by
+manually adding typings for it:
+
+1. First, create a `typings.d.ts` file in your `src/` folder. This file will be automatically included as global type definition.
+
+2. Then, in `src/typings.d.ts`, add the following code:
+
+  ```typescript
+  declare module 'typeless-package';
+  ```
+
+3. Finally, in the component or file that uses the library, add the following code:
+
+  ```typescript
+  import * as typelessPackage from 'typeless-package';
+  typelessPackage.method();
+  ```
+
+Done. Note: you might need or find useful to define more typings for the library that you're trying to use.
diff --git a/docs/documentation/test.md b/docs/documentation/test.md
@@ -5,6 +5,18 @@
 ## Overview
 `ng test` compiles the application into an output directory
 
+### Running unit tests
+
+```bash
+ng test
+```
+
+Tests will execute after a build is executed via [Karma](http://karma-runner.github.io/0.13/index.html), and it will automatically watch your files for changes. You can run tests a single time via `--watch=false` or `--single-run`.
+
+You can run tests with coverage via `--code-coverage`. The coverage report will be in the `coverage/` directory.
+
+Linting during tests is also available via the `--lint` flag. See [Linting and formatting code](#linting-and-formatting-code) chapter for more informations.
+
 ## Options
 `--watch` (`-w`) flag to run builds when files change
 
