Go to file

Tero Parviainen 4acbef19a8 docs(upgrade): add ngUpgrade guide version 2

closes #1538
This is a major reorganization of the Upgrade guide.

* Compatible with the new version of the AngularJS 1 PhoneCat
  tutorial.
* No longer switching Angular 1 code to SystemJS for PhoneCat,
  to allow beginning Angular 2 migration with fewer preparation
  steps. SystemJS switch now happens simultaneously with upgrade.
  (This is based on input from @joeeames)
* Testing moved to an appendix to make the main narrative
  shorter and easier to follow.
* Use component methods to do phone filtering and ordering
  instead of introducing pipes to replace filterFilter and orderByFilter.
* Cover issue with camelCase inputs on downgraded components.

For authors:

* All examples now fully integrated with the example boilerplate. Uses the
  same Angular 2 version as all other guides. E2E tests are executed
  along with all the others.
* Reduced number of PhoneCat versions from five to three.
* Each directory has a README explaining how to run it and what might
  be peculiar about it.

Closes angular/angular#8622
Relates to angular/angular.js#14416
Relates to angular/angular-phonecat#326

2016-05-28 09:33:06 -07:00

public

docs(upgrade): add ngUpgrade guide version 2

2016-05-28 09:33:06 -07:00

tools

chore: more conversion of es6-shim to core-js

2016-05-19 23:18:18 -07:00

.editorconfig

chore: replace VSCode-specific settings.json with broadly recommended .editorconfig

2016-04-05 10:15:27 -07:00

.gitignore

[review-pending] docs(dev guide): server-communication - new prose

2016-05-13 21:32:54 +01:00

.travis.yml

chore(travis): add Travis CI

2016-05-25 16:47:30 -07:00

firebase.json

chore(routing): add a short route for the styleguide

2016-05-03 18:46:54 -07:00

gulpfile.js

fix(gulp): rename angular2 to @angular, fixes api doc examples

2016-05-26 09:22:25 -07:00

harp.json

chore(bio): Added missing website for Stephen

2016-05-10 17:10:24 -07:00

LICENSE

chore: update license to MIT

2016-01-08 14:10:38 -08:00

package.json

api-builder: update to dgeni-packages 0.13.0

2016-05-12 03:40:57 -07:00

README.md

chore: update README with more e2e explanations

2016-05-21 15:11:22 -07:00

tslint.json

docs(style-guide): add style-guide - v.6

2016-05-01 16:08:45 -07:00

README.md

Angular.io

Angular.io is site for Angular 2 documentation .

This site also includes links to other helpful angular resources including Angular 2, Angular 1, Angular Material, and AngularFire.

Issues

Please file Developer Guide, Cookbook, and code sample issues only in this Angular.io github repo.

Angular API issues, cheatsheet corrections, feature requests, defect reports, and technical questions concerning Angular itself belong in the angular source code github repo. We can't handle those topics here and will ask you to re-post them on the angular repo.

How you can help

Filing issues is helpful but pull requests that improve the docs are even better!

Learn how to contribute to Angular.io.

Development Setup

This site relies heavily on node and npm.

Make sure you are using the latest node and npm; if not install nvm to get node going on your machine.
install these npm packages globally: npm install -g harp gulp protractor
clone this repo and the angular source code repo to the same parent directory. The two cloned repo directories must be sibling.
cd into root directory Angular.io/
install the all-docs local packages by running npm install

If running node v.5+, you probably must rebuild node-sass in a separate step: npm rebuild node-sass

See below for code sample development preparation.

Content Development

All documentation content is written in Jade which has its own syntax. Be aware of the strict demands imposed by this significant-whitespace language. We strongly recommend running one of the gulp serve-and-sync commands described below while editing content so you can see the effect of your changes as you type.

The documentation relies on specific styles and mixins. Learn about those in the documentation styleguide.

The jade documentation files are language-specific directories under either public/docs/. For example, all of the TypeScript docs are in public/docs/ts/latest, e.g.

public/docs/ts/latest/quickstart.jade
public/docs/ts/latest/guide/architecture.jade
public/docs/ts/latest/cookbook/component-communication.jade
public/docs/ts/latest/tutorial/toh-pt5.jade

Local server with watches and browser reload

cd into root directory Angular.io/
run gulp serve-and-sync
browser will launch on localhost:3000 and stay refreshed automatically.

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:

gulp serve-and-sync : watch all the local Jade/Sass files, the API source and examples, and the dev guide files
gulp serve-and-sync-api : watch only the API source and example files
gulp serve-and-sync-devguide : watch only the dev guide files
gulp build-and-serve : watch only the local Jade/Sass files

Code Sample Development

All documentation is supported by sample code and plunkers. Such code resides in the public/docs/_examples directory, under chapter-specific directories, further divided by language track.

For example, the TypeScript QuickStart sample is in public/docs/_examples/quickstart/ts.

All samples are in a consistent directory structure using the same styles and the same npm packages, including the latest release of Angular 2. This consistency is possible in part thanks to gulp-driven tooling. To run the samples locally and confirm that they work properly, take the following extra steps to prepare the environment:

cd to public/docs/_examples
install the canonical node packages for all samples by running npm install
cd back up to Angular.io root: cd ../../..
run gulp add-example-boilerplate (elevate to admin on Windows) to copy canonical files to the sample directories and create symlinks there for node_modules and typings.

Now cd into any particular sample's language directory (e.g., public/docs/_examples/quickstart/ts) and try:

npm start to simultaneously compile-with-watch and serve-in-browser-with-watch
npm run tsc to compile only
npm run lite to serve-and-watch in browser

Look at the scripts in package.json for other options. Also, open any plunkr.no-link.html to see the code execute in plunker (you may have to run gulp build-plunkers first to create/update).

Sample end-to-end tests

All samples should be covered to some degree by end-to-end tests:

gulp run-e2e-tests to run all TypeScript and JavaScript tests
gulp run-e2e-tests --lang=dart to run all Dart tests
gulp run-e2e-tests --lang=all to run TypeScript, JavaScript, and Dart tests
gulp run-e2e-tests --filter=quickstart to filter the examples to run, by name
gulp run-e2e-tests --fast to ignore npm install, webdriver update and boilerplate copy

Any combination of options is possible.

Technology Used

Angular 1.x: The production ready version of Angular
Angular Material: An implementation of Material Design in Angular.js
Gulp: node-based tooling
Harp: The static web server with built-in preprocessing.
Sass: A professional grade CSS extension language
Normalize: A modern, HTML5-ready alternative to CSS resets
Grids: A highly customizable CSS Grid Framework built with Sass
Prettify: A JS module and CSS for syntax highlighting of source code snippets.
Icomoon: Custom built icon fonts

License

Languages

TypeScript 68.6%

HTML 12.8%

JavaScript 8.4%

Pug 7%

Starlark 1.4%

Other 1.7%