From 90adda48174622b2e4d9228b5ad26392c31b21dd Mon Sep 17 00:00:00 2001 From: Mike Brocchi Date: Sun, 22 Jan 2017 22:51:36 -0500 Subject: [PATCH] docs: move documentation from readme to docs --- .editorconfig | 2 +- README.md | 11 ++- docs/documentation/build.md | 69 ++++++++++++++++--- docs/documentation/e2e.md | 10 +++ docs/documentation/lint.md | 8 +++ .../stories/css-preprocessors.md | 32 +++++++++ .../stories/deploy-github-pages.md | 30 ++++++++ docs/documentation/stories/global-lib.md | 35 ++++++++++ docs/documentation/stories/global-styles.md | 9 +++ docs/documentation/stories/proxy.md | 28 ++++++++ docs/documentation/stories/third-party-lib.md | 30 ++++++++ docs/documentation/test.md | 12 ++++ 12 files changed, 261 insertions(+), 15 deletions(-) create mode 100644 docs/documentation/lint.md create mode 100644 docs/documentation/stories/css-preprocessors.md create mode 100644 docs/documentation/stories/deploy-github-pages.md create mode 100644 docs/documentation/stories/global-lib.md create mode 100644 docs/documentation/stories/global-styles.md create mode 100644 docs/documentation/stories/proxy.md create mode 100644 docs/documentation/stories/third-party-lib.md diff --git a/.editorconfig b/.editorconfig index e0f1dae3a7d9..b53765a86c8d 100644 --- 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 index 218d3b3b06e3..75b8fe19ba1d 100644 --- 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. - + ### Creating a build ```bash @@ -268,7 +268,6 @@ 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. - ### Linting and formatting code You can lint your app code by running `ng lint`. @@ -276,6 +275,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. + + + ### Commands autocompletion To turn on auto completion use the following commands: @@ -308,6 +310,7 @@ You use the `assets` array in `angular-cli.json` to list files or folders you wa ] ``` + ### Global styles The `styles.css` file allows users to add global styles and supports @@ -418,6 +421,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. + + ### 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 index 0c1cdeef7d7a..3d14bd990c33 100644 --- a/docs/documentation/build.md +++ b/docs/documentation/build.md @@ -3,27 +3,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 (``) 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 index 792aae685b55..d761d338d736 100644 --- a/docs/documentation/e2e.md +++ b/docs/documentation/e2e.md @@ -2,3 +2,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 new file mode 100644 index 000000000000..189451c4d7cc --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/documentation/stories/css-preprocessors.md b/docs/documentation/stories/css-preprocessors.md new file mode 100644 index 000000000000..b8661e8d7494 --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/documentation/stories/deploy-github-pages.md b/docs/documentation/stories/deploy-github-pages.md new file mode 100644 index 000000000000..f062852f6b4e --- /dev/null +++ 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 new file mode 100644 index 000000000000..22f8508e0b7e --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/documentation/stories/global-styles.md b/docs/documentation/stories/global-styles.md new file mode 100644 index 000000000000..bde05c290546 --- /dev/null +++ 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 new file mode 100644 index 000000000000..7ca5a45b786f --- /dev/null +++ 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` \ No newline at end of file diff --git a/docs/documentation/stories/third-party-lib.md b/docs/documentation/stories/third-party-lib.md new file mode 100644 index 000000000000..2d78b5787000 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/documentation/test.md b/docs/documentation/test.md index d71fce0d9982..947c755d93c9 100644 --- a/docs/documentation/test.md +++ b/docs/documentation/test.md @@ -3,6 +3,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