docs: Add getting started walkthrough + developer guide (#41)

* Add `developer.md` guide * Update `getting-started.md` * Update `README.md`
trimox · Jul 6, 2017 · f6cdba1 · f6cdba1
1 parent 8e1272a
commit f6cdba1
Show file tree

Hide file tree

Showing 3 changed files with 139 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -9,19 +9,28 @@
 Our Angular library integrates with [Google's Material Design Components](https://material.io/components/), providing a faithful and accurate representation of Material Design as it is envisioned on the web platform by Google's Material Design team. Our goal is to equip Angular developers with modular, straightforward and production-ready Material Design components.
 
 ### Quick Links
-*  [Contributing](https://github.com/trimox/angular-mdc-web/blob/master/CONTRIBUTING.md)
 *  [Changelog](https://github.com/trimox/angular-mdc-web/blob/master/CHANGELOG.md)
+*  [Contributing](https://github.com/trimox/angular-mdc-web/blob/master/CONTRIBUTING.md)
+*  [Developer guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/developer.md)
+*  [Demo App](https://trimox.github.io/angular-mdc-web/)
+*  [Getting Started guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/getting-started.md)
 *  [Gitter Chat](https://gitter.im/angular-mdc/Lobby)
+*  [StackOverflow](https://stackoverflow.com/questions/tagged/angular-mdc) `tag: angular-mdc`
 
-## Installation
+## Install Angular MDC
 ```
 npm install --save @angular-mdc/web
 ```
 
+## Updating Angular MDC version
+```
+npm update
+```
+
 ## Getting started
 Check out our [Getting Started guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/getting-started.md) to begin adopting  Angular MDC in your project.
 
-### Material Design Components
+## Material Design Components
 * WIP = work in progress
 * TBI = to be implemented
 
@@ -30,13 +39,13 @@ Check out our [Getting Started guide](https://github.com/trimox/angular-mdc-web/
 | button | Available |
 | card | Available |
 | checkbox | Available |
-| dialog | TBI |
-| drawer | TBI |
+| dialog | WIP |
+| drawer | WIP |
 | elevation | Available |
 | fab | Available |
 | form-field | Available |
 | grid-list | TBI |
-| icon-toggle | TBI |
+| icon-toggle | WIP |
 | linear-progress | Available |
 | list | TBI |
 | menu | Available |
@@ -52,18 +61,15 @@ Check out our [Getting Started guide](https://github.com/trimox/angular-mdc-web/
 | toolbar | Available |
 | typography | Available |
 
-## Running the demo app
-
-Clone and install repo:
-```
-git clone https://github.com/trimox/angular-mdc-web.git && cd angular-mdc-web
-npm i
-```
-
-Run the webpack development server (content served from `src/demo-app/`):
-```
-cd /path/to/angular-mdc-web
-npm run start
-open http://localhost:4000
-```
+## Developing Angular MDC
+Want to develop your own components or change existing ones? Check out our [Developer guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/developer.md).
 
+## Browser Support
+We officially support the last two versions of every major browser.
+* Chrome
+* Safari
+* Firefox
+* IE 11/Edge
+* Opera
+* Mobile Safari
+* Chrome on Android
diff --git a/docs/developer.md b/docs/developer.md
@@ -0,0 +1,61 @@
+# Developing for Angular MDC
+
+ - [Infrastructure and Tooling](#tools)
+ - [Setup your development environment](#setup)
+ - [Running the Development Server](#dev-server)
+ - [Linting / Testing](#lint)
+ - [Building](#build)
+ - [Code Style](#code-style)
+ - [Submit Pull Request](#pull-req)
+
+## <a name="tools"></a> Infrastructure and Tooling
+
+Build System
+- [Rollup](https://github.com/rollup/rollup)
+  * Provides next-generation ES6 module bundling.
+
+Development Server
+- [WebPack](https://webpack.js.org/)
+  - Fast, modern development environment (incremental compilation, source maps, live reloading, etc.)
+
+## <a name="setup"></a> Setup up your development environment
+You'll need a recent version of nodejs.
+```
+npm i npm@latest -g
+```
+Once node is installed, simply clone our repo (or your fork of it) and install developer dependencies.
+```
+git clone https://github.com/trimox/angular-mdc-web.git  # or a path to your fork
+cd angular-mdc-web
+npm i # Install developer dependencies
+```
+
+## <a name="dev-server"></a> Running the development server
+Run a webpack-dev-server instance that should assist with initial development. (content served from `src/demo-app/`)
+```
+cd /path/to/angular-mdc-web
+npm run start
+```
+Open your browser to http://localhost:4000
+
+## <a name="lint"></a> Linting / Testing
+```
+npm run lint:ts # Lints typescript using tslint
+npm run lint:css # Lints (S)CSS using stylelint
+npm run lint # Runs both of the above commands in parallel
+```
+
+## <a name="build"></a> Building Angular MDC
+```
+npm run build # Builds Angular MDC inside of dist/
+```
+
+## <a name="code-style"></a> Code Style
+Our entire coding style is enforced automatically through the use of linters. We also follow [Google's JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html).
+* [tslint rules](https://github.com/trimox/angular-mdc-web/blob/master/tslint.json)
+* [stylelint config](https://github.com/trimox/angular-mdc-web/blob/master/.stylelint-config.yaml)
+
+## <a name="pull-req"></a> Submit a Pull Request
+When submitting PRs, make sure you're following our commit message conventions; our commit-msg hook should automatically enforce this. We also use [commitizen](https://www.npmjs.com/package/commitizen), which you can use to auto-format commit messages for you.
+
+When submitting PRs for large changes, be sure to include an adequate background in the description so that reviewers of the PR know what the changes entail at a high-level, the motivations for making these changes, and what they affect.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,11 +1,21 @@
-# Getting Started
+Follow these steps to begin begin adopting Angular MDC.
 
-### Install Angular MDC
+ - [Step 1 - Install Angular MDC](#step1)
+ - [Step 2 - Import Components](#step2)
+ - [Step 3 - MDC Theme](#step3)
+ - [Step 4 - Material Design Icons](#step4)
+ - [Step 5 - Roboto Font](#step5)
+ - [Step 6 - Typography](#step6)
+ - [Appendix - Sample index.html](#sample-html)
+ - [Appendix - Configuring SystemJS](#config-systemjs)
+
+## <a name="step1"></a> Step 1: Install Angular MDC
 ```
 npm install --save @angular-mdc/web
 ```
 
-### Include all components
+## <a name="step2"></a> Step 2: Import Components
+### All components
 ```ts
 import { MaterialModule } from '@angular-mdc/web';
 
@@ -17,7 +27,7 @@ import { MaterialModule } from '@angular-mdc/web';
 export class ExampleModule { }
 ```
 
-### Or choose individual components
+### Or individual components
 ```ts
 import { FabModule, MenuModule } from '@angular-mdc/web';
 
@@ -29,43 +39,72 @@ import { FabModule, MenuModule } from '@angular-mdc/web';
 export class ExampleModule { }
 ```
 
-### Include Material Design Components Theme (required)
-Apply the MDC theme to all core components.
+## <a name="step3"></a> Step 3: MDC Theme
+Including the MDC theme is required to apply all of the core and theme styles to your application.
+
+If you're using the Angular CLI, you can add this to your styles.css:
 ```ts
 @import "material-components-web/material-components-web";
 ```
 
-### Use Material Design Icons
+Alternatively, you can use a CDN.
+```html
+<link href="https://unpkg.com/material-components-web/dist/material-components-web.css" rel="stylesheet">
+```
+Or link directly to the node_modules file.
+```html
+<link href="node_modules/material-components-web/dist/material-components-web.css" rel="stylesheet">
+```
+
+## <a name="step4"></a> Step 4: Material Design Icons
 Add the [Material Design Icons](https://material.io/icons/) collection to your `index.html`.
 
 ```html
 <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
 ```
 
-### Use Roboto Font
+## <a name="step5"></a> Step 5: Roboto Font
 Add the Roboto font with 300, 400 and 500 weights to your `index.html`.
 
 ```html
 <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet">
- ```
- 
-### Apply MDC Typography
-Add the `mdc-typography` directive to your body element to define basic properties for text, such as the Roboto typeface and antialiasing settings.
+```
+
+## <a name="step6"></a> Step 6: Typography (optional)
+Add the `mdc-typography` directive to your body element to define basic properties for text, such as the Roboto typeface and antialiasing settings throughout your app.
 
 ```html
 <body mdc-typography>
 ```
 
-### Sample index.html
+## <a name="sample-html"></a> Appendix: Sample index.html
 ```html
 <!DOCTYPE html>
 <html>
   <head>
     <title>Angular MDC</title>
     <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet">
     <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+    <link href="https://unpkg.com/material-components-web/dist/material-components-web.css" rel="stylesheet">
   </head>
   <body mdc-typography>
+    <!--page content-->
   </body>
 </html>
 ```
+
+## <a name="config-systemjs"></a> Appendix: Configuring SystemJS
+
+If your project is using SystemJS for module loading, you will need to add `@angular-mdc/web`
+to the SystemJS configuration:
+
+```js
+System.config({
+  // existing configuration options
+  map: {
+    // ...
+    '@angular-mdc/web': 'npm:@angular-mdc/web/bundles/material.umd.js',
+    // ...
+  }
+});
+```