Skip to content

Commit 092e673

Browse files
Broccofilipesilva
authored andcommitted
docs: move documentation from readme to docs
Close #4190
1 parent 26003a0 commit 092e673

12 files changed

+261
-14
lines changed

.editorconfig

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ trim_trailing_whitespace = true
1111

1212
[*.md]
1313
insert_final_newline = false
14-
trim_trailing_whitespace = false
14+
trim_trailing_whitespace = true

README.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -122,12 +122,12 @@ The CLI supports routing in several ways:
122122
- 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.
123123

124124
The file includes an empty `Routes` object that you can fill with routes to different components and/or modules.
125-
125+
126126
The `--routing` option also generates a default component with the same name as the module.
127127

128128
- 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.
129129

130-
130+
<!-- DeleteSection1 Start here to remove upon next release -->
131131
### Creating a build
132132

133133
```bash
@@ -276,6 +276,9 @@ This will use the `lint` npm script that in generated projects uses `tslint`.
276276

277277
You can modify the these scripts in `package.json` to run whatever tool you prefer.
278278

279+
<!-- DeleteSection1 End here -->
280+
281+
<!-- consider removing autocompletion from readme -->
279282
### Commands autocompletion
280283

281284
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
308311
]
309312
```
310313

314+
<!-- DeleteSection2 Start here to remove upon next release -->
311315
### Global styles
312316

313317
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:
418422
Restart `ng serve` if you're running it, and Bootstrap 4 should be working on
419423
your app.
420424

425+
<!-- DeleteSection2 End here -->
426+
421427
### Updating angular-cli
422428

423429
To update `angular-cli` to a new version, you must update both the global package and your project's local package.

docs/documentation/build.md

Lines changed: 58 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,27 +5,74 @@
55
## Overview
66
`ng build` compiles the application into an output directory
77

8-
## Options
9-
`--target` (`-t`) define the build target
8+
### Creating a build
109

11-
`--environment` (`-e`) defines the build environment
10+
```bash
11+
ng build
12+
```
1213

13-
`--prod` flag to set build target and environment to production
14+
The build artifacts will be stored in the `dist/` directory.
1415

15-
`--dev` flag to set build target and environment to development
16+
### Build Targets and Environment Files
17+
18+
`ng build` can specify both a build target (`--target=production` or `--target=development`) and an
19+
environment file to be used with that build (`--environment=dev` or `--environment=prod`).
20+
By default, the development build target and environment are used.
21+
22+
The mapping used to determine which environment file is used can be found in `angular-cli.json`:
23+
24+
```json
25+
"environments": {
26+
"source": "environments/environment.ts",
27+
"dev": "environments/environment.ts",
28+
"prod": "environments/environment.prod.ts"
29+
}
30+
```
31+
32+
These options also apply to the serve command. If you do not pass a value for `environment`,
33+
it will default to `dev` for `development` and `prod` for `production`.
1634

1735
```bash
1836
# these are equivalent
19-
--target=production --environment=prod
20-
--prod --env=prod
21-
--prod
37+
ng build --target=production --environment=prod
38+
ng build --prod --env=prod
39+
ng build --prod
2240
# and so are these
23-
--target=development --environment=dev
24-
--dev --e=dev
25-
--dev
41+
ng build --target=development --environment=dev
42+
ng build --dev --e=dev
43+
ng build --dev
2644
ng build
2745
```
2846

47+
You can also add your own env files other than `dev` and `prod` by doing the following:
48+
- create a `src/environments/environment.NAME.ts`
49+
- add `{ "NAME": 'src/environments/environment.NAME.ts' }` to the `apps[0].environments` object in `angular-cli.json`
50+
- use them via the `--env=NAME` flag on the build/serve commands.
51+
52+
### Base tag handling in index.html
53+
54+
When building you can modify base tag (`<base href="/">`) in your index.html with `--base-href your-url` option.
55+
56+
```bash
57+
# Sets base tag href to /myUrl/ in your index.html
58+
ng build --base-href /myUrl/
59+
ng build --bh /myUrl/
60+
```
61+
62+
### Bundling
63+
64+
All builds make use of bundling, and using the `--prod` flag in `ng build --prod`
65+
or `ng serve --prod` will also make use of uglifying and tree-shaking functionality.
66+
67+
## Options
68+
`--target` (`-t`) define the build target
69+
70+
`--environment` (`-e`) defines the build environment
71+
72+
`--prod` flag to set build target and environment to production
73+
74+
`--dev` flag to set build target and environment to development
75+
2976
`--output-path` (`-o`) path where output will be placed
3077

3178
`--output-hashing` define the output filename cache-busting hashing mode

docs/documentation/e2e.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,13 @@
44

55
## Overview
66
`ng e2e` executes end-to-end tests
7+
8+
### Running end-to-end tests
9+
10+
```bash
11+
ng e2e
12+
```
13+
14+
Before running the tests make sure you are serving the app via `ng serve`.
15+
16+
End-to-end tests are run via [Protractor](https://angular.github.io/protractor/).

docs/documentation/lint.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# ng lint
2+
3+
## Overview
4+
`ng lint` will lint your app code.
5+
6+
This will use the `lint` npm script that in generated projects uses `tslint`.
7+
8+
You can modify the these scripts in `package.json` to run whatever tool you prefer.
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# CSS Preprocessor integration
2+
3+
Angular-CLI supports all major CSS preprocessors:
4+
- sass/scss ([http://sass-lang.com/](http://sass-lang.com/))
5+
- less ([http://lesscss.org/](http://lesscss.org/))
6+
- stylus ([http://stylus-lang.com/](http://stylus-lang.com/))
7+
8+
To use these preprocessors simply add the file to your component's `styleUrls`:
9+
10+
```javascript
11+
@Component({
12+
selector: 'app-root',
13+
templateUrl: './app.component.html',
14+
styleUrls: ['./app.component.scss']
15+
})
16+
export class AppComponent {
17+
title = 'app works!';
18+
}
19+
```
20+
21+
When generating a new project you can also define which extension you want for
22+
style files:
23+
24+
```bash
25+
ng new sassy-project --style=sass
26+
```
27+
28+
Or set the default style on an existing project:
29+
30+
```bash
31+
ng set defaults.styleExt scss
32+
```
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Deploying the app via GitHub Pages
2+
3+
You can deploy your apps quickly via:
4+
5+
```bash
6+
ng github-pages:deploy --message "Optional commit message"
7+
```
8+
9+
This will do the following:
10+
11+
- creates GitHub repo for the current project if one doesn't exist
12+
- rebuilds the app in production mode at the current `HEAD`
13+
- creates a local `gh-pages` branch if one doesn't exist
14+
- moves your app to the `gh-pages` branch and creates a commit
15+
- edit the base tag in index.html to support GitHub Pages
16+
- pushes the `gh-pages` branch to GitHub
17+
- returns back to the original `HEAD`
18+
19+
Creating the repo requires a token from GitHub, and the remaining functionality
20+
relies on ssh authentication for all git operations that communicate with github.com.
21+
To simplify the authentication, be sure to [setup your ssh keys](https://help.github.com/articles/generating-ssh-keys/).
22+
23+
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:
24+
25+
```bash
26+
ng github-pages:deploy --user-page --message "Optional commit message"
27+
```
28+
29+
This command pushes the app to the `master` branch on the GitHub repo instead
30+
of pushing to `gh-pages`, since user and organization pages require this.
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Global Library Installation
2+
3+
Some javascript libraries need to be added to the global scope, and loaded as if
4+
they were in a script tag. We can do this using the `apps[0].scripts` and
5+
`apps[0].styles` properties of `angular-cli.json`.
6+
7+
As an example, to use [Bootstrap 4](http://v4-alpha.getbootstrap.com/) this is
8+
what you need to do:
9+
10+
First install Bootstrap from `npm`:
11+
12+
```bash
13+
npm install bootstrap@next
14+
```
15+
16+
Then add the needed script files to `apps[0].scripts`:
17+
18+
```json
19+
"scripts": [
20+
"../node_modules/jquery/dist/jquery.js",
21+
"../node_modules/tether/dist/js/tether.js",
22+
"../node_modules/bootstrap/dist/js/bootstrap.js"
23+
],
24+
```
25+
26+
Finally add the Bootstrap CSS to the `apps[0].styles` array:
27+
```json
28+
"styles": [
29+
"../node_modules/bootstrap/dist/css/bootstrap.css",
30+
"styles.css"
31+
],
32+
```
33+
34+
Restart `ng serve` if you're running it, and Bootstrap 4 should be working on
35+
your app.
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Global styles
2+
3+
The `styles.css` file allows users to add global styles and supports
4+
[CSS imports](https://developer.mozilla.org/en/docs/Web/CSS/@import).
5+
6+
If the project is created with the `--style=sass` option, this will be a `.sass`
7+
file instead, and the same applies to `scss/less/styl`.
8+
9+
You can add more global styles via the `apps[0].styles` property in `angular-cli.json`.

docs/documentation/stories/proxy.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Proxy To Backend
2+
3+
Using the proxying support in webpack's dev server we can highjack certain urls and send them to a backend server.
4+
We do this by passing a file to `--proxy-config`
5+
6+
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.
7+
8+
We create a file next to projects `package.json` called `proxy.conf.json`
9+
with the content
10+
11+
```json
12+
{
13+
"/api": {
14+
"target": "http://localhost:3000",
15+
"secure": false
16+
}
17+
}
18+
```
19+
20+
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)
21+
22+
and then we edit the `package.json` file's start script to be
23+
24+
```json
25+
"start": "ng serve --proxy-config proxy.conf.json",
26+
```
27+
28+
now run it with `npm start`
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# 3rd Party Library Installation
2+
3+
Simply install your library via `npm install lib-name --save` and import it in your code.
4+
5+
If the library does not include typings, you can install them using npm:
6+
7+
```bash
8+
npm install d3 --save
9+
npm install @types/d3 --save-dev
10+
```
11+
12+
If the library doesn't have typings available at `@types/`, you can still use it by
13+
manually adding typings for it:
14+
15+
1. First, create a `typings.d.ts` file in your `src/` folder. This file will be automatically included as global type definition.
16+
17+
2. Then, in `src/typings.d.ts`, add the following code:
18+
19+
```typescript
20+
declare module 'typeless-package';
21+
```
22+
23+
3. Finally, in the component or file that uses the library, add the following code:
24+
25+
```typescript
26+
import * as typelessPackage from 'typeless-package';
27+
typelessPackage.method();
28+
```
29+
30+
Done. Note: you might need or find useful to define more typings for the library that you're trying to use.

docs/documentation/test.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,18 @@
55
## Overview
66
`ng test` compiles the application into an output directory
77

8+
### Running unit tests
9+
10+
```bash
11+
ng test
12+
```
13+
14+
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`.
15+
16+
You can run tests with coverage via `--code-coverage`. The coverage report will be in the `coverage/` directory.
17+
18+
Linting during tests is also available via the `--lint` flag. See [Linting and formatting code](#linting-and-formatting-code) chapter for more informations.
19+
820
## Options
921
`--watch` (`-w`) flag to run builds when files change
1022

0 commit comments

Comments
 (0)