|
| 1 | +# Angular.io |
| 2 | +Angular.io is site for Angular 2 **documentation** . |
| 3 | + |
| 4 | +This site also includes links to other helpful angular resources including |
| 5 | +Angular 2, Angular 1, Angular Material, and AngularFire. |
| 6 | + |
| 7 | +## Issues |
| 8 | + |
| 9 | +Please file **Developer Guide, Cookbook, and code sample issues _only_** in this |
| 10 | +[Angular.io](https://github.com/angular/angular.io/issues) github repo. |
| 11 | + |
| 12 | +**Angular API issues, cheatsheet corrections, feature requests, defect reports, and technical questions** concerning Angular itself |
| 13 | +belong in the [**angular source code**](https://github.com/angular/angular/issues) github repo. |
| 14 | +We can't handle those topics here and will ask you to re-post them on the angular repo. |
| 15 | + |
| 16 | +## How you can help |
| 17 | + |
| 18 | +Filing issues is helpful but **pull requests** that improve the docs are even better! |
| 19 | + |
| 20 | +Learn how to [contribute to Angular.io](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md). |
| 21 | + |
| 22 | +## Development Setup |
| 23 | +This site relies heavily on node and npm. |
| 24 | + |
| 25 | +1. Make sure you are using the latest node and npm; |
| 26 | +if not install [nvm](https://github.com/creationix/nvm) to get node going on your machine. |
| 27 | + |
| 28 | +1. install these npm packages *globally*: `npm install -g harp gulp protractor` |
| 29 | + |
| 30 | +1. clone this repo and the [angular source code repo](https://github.com/angular/angular) to the same parent directory. |
| 31 | +The two cloned repo directories must be sibling. |
| 32 | + |
| 33 | +1. cd into root directory `Angular.io/` |
| 34 | + |
| 35 | +1. install the *all-docs* local packages by running `npm install` |
| 36 | +> If running node v.5+, you probably must rebuild `node-sass` in a separate step: `npm rebuild node-sass` |
| 37 | +
|
| 38 | +1. See [below](#code-sample-development) for code sample development preparation. |
| 39 | + |
| 40 | +## Content Development |
| 41 | +All documentation content is written in Jade which has [its own syntax](http://jade-lang.com/reference/). |
| 42 | +Be aware of the strict demands imposed by this significant-whitespace language. |
| 43 | +We strongly recommend running one of the gulp `serve-and-sync` commands [described below](#serve-and-sync) |
| 44 | +while editing content so you can see the effect of your changes *as you type*. |
| 45 | + |
| 46 | +The documentation relies on specific styles and mixins. |
| 47 | +Learn about those in the [documentation styleguide](https://angular.io/docs/ts/latest/styleguide.html). |
| 48 | + |
| 49 | +The jade documentation files are language-specific directories under either `public/docs/`. |
| 50 | +For example, all of the TypeScript docs are in `public/docs/ts/latest`, e.g. |
| 51 | +- `public/docs/ts/latest/quickstart.jade` |
| 52 | +- `public/docs/ts/latest/guide/architecture.jade` |
| 53 | +- `public/docs/ts/latest/cookbook/component-communication.jade` |
| 54 | +- `public/docs/ts/latest/tutorial/toh-pt5.jade` |
| 55 | + |
| 56 | +### Local server with watches and browser reload |
| 57 | + 1. cd into root directory `Angular.io/` |
| 58 | + 1. run `gulp serve-and-sync` |
| 59 | + 1. browser will launch on localhost:3000 and stay refreshed automatically. |
| 60 | + |
| 61 | +<a id="serve-and-sync"></a> |
| 62 | +If you are only going to work on a specific part of the docs, such as the dev guide, then you can use one of the more specific gulp tasks to only watch those parts of the file system: |
| 63 | + |
| 64 | +* `gulp serve-and-sync` : watch all the local Jade/Sass files, the API source and examples, and the dev guide files |
| 65 | +* `gulp serve-and-sync-api` : watch only the API source and example files |
| 66 | +* `gulp serve-and-sync-devguide` : watch only the dev guide files |
| 67 | +* `gulp build-and-serve` : watch only the local Jade/Sass files |
| 68 | + |
| 69 | +## Code Sample Development |
| 70 | + |
| 71 | +All documentation is supported by sample code and plunkers. |
| 72 | +Such code resides in the `public/docs/_examples` directory, under chapter-specific directories, further divided by language track. |
| 73 | + |
| 74 | +For example, the TypeScript QuickStart sample is in `public/docs/_examples/quickstart/ts`. |
| 75 | + |
| 76 | +All samples are in a consistent directory structure using the same styles and the same npm packages, including the latest release of Angular 2. |
| 77 | +This consistency is possible in part thanks to gulp-driven tooling. |
| 78 | +To run the samples locally and confirm that they work properly, |
| 79 | +take the following extra steps to prepare the environment: |
| 80 | + |
| 81 | +1. cd to `public/docs/_examples` |
| 82 | + |
| 83 | +1. install the canonical node packages for all samples by running `npm install` |
| 84 | + |
| 85 | +1. cd back up to `Angular.io` root: `cd ../../..` |
| 86 | + |
| 87 | +1. run `gulp add-example-boilerplate` (elevate to admin on Windows) |
| 88 | +to copy canonical files to the sample directories and create symlinks there for node_modules and typings. |
| 89 | + |
| 90 | +Now cd into any particular sample's language directory (e.g., `public/docs/_examples/quickstart/ts`) and try: |
| 91 | +- `npm start` to simultaneously compile-with-watch and serve-in-browser-with-watch |
| 92 | +- `npm run tsc` to compile only |
| 93 | +- `npm run lite` to serve-and-watch in browser |
| 94 | + |
| 95 | +Look at the scripts in `package.json` for other options. |
| 96 | +Also, open any `plunkr.no-link.html` to see the code execute in plunker |
| 97 | +(you may have to run `gulp build-plunkers` first to create/update). |
| 98 | + |
| 99 | +### Sample end-to-end tests |
| 100 | + |
| 101 | +All samples should be covered to some degree by end-to-end tests: |
| 102 | +- `gulp run-e2e-tests` to run all TypeScript and JavaScript tests |
| 103 | +- `gulp run-e2e-tests --lang=dart` to run all Dart tests |
| 104 | +- `gulp run-e2e-tests --lang=all` to run TypeScript, JavaScript, and Dart tests |
| 105 | +- `gulp run-e2e-tests --filter=quickstart` to filter the examples to run, by name |
| 106 | +- `gulp run-e2e-tests --fast` to ignore npm install, webdriver update and boilerplate copy |
| 107 | + |
| 108 | +Any combination of options is possible. |
| 109 | + |
| 110 | + |
| 111 | +## Technology Used |
| 112 | +- Angular 1.x: The production ready version of Angular |
| 113 | +- Angular Material: An implementation of Material Design in Angular.js |
| 114 | +- Gulp: node-based tooling |
| 115 | +- Harp: The static web server with built-in preprocessing. |
| 116 | +- Sass: A professional grade CSS extension language |
| 117 | +- Normalize: A modern, HTML5-ready alternative to CSS resets |
| 118 | +- Grids: A highly customizable CSS Grid Framework built with Sass |
| 119 | +- Prettify: A JS module and CSS for syntax highlighting of source code snippets. |
| 120 | +- Icomoon: Custom built icon fonts |
| 121 | + |
| 122 | + |
| 123 | +## License |
| 124 | +Powered by Google ©2010-2016. Code licensed under an [MIT-style License](https://github.com/angular.io/blob/master/LICENSE). Documentation licensed under [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/). |
0 commit comments