From 48dcbc21f10d1a8233cb3835bc4fe20644a00a6d Mon Sep 17 00:00:00 2001 From: Ed Morales Date: Fri, 30 Dec 2016 10:35:25 -0700 Subject: [PATCH] feature(docs): getting started docs + improvements. (closes #178) (#218) * first draft on getting started docs * guideline to avoid effort duplication in CONTRIBUTING.md * removed outdated docs in DEVELOPER_GUIDE.md * changed NODE minimum dep to 5.5.0 * added instructions for optional covalent modules * update(readme): tweak versions & link to quickstart --- README.md | 10 +-- docs/CONTRIBUTING.md | 1 + docs/DEVELOPER_GUIDE.md | 4 +- docs/GETTING_STARTED.md | 134 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 142 insertions(+), 7 deletions(-) create mode 100644 docs/GETTING_STARTED.md diff --git a/README.md b/README.md index dd7699e230..0c61758265 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -## Covalent: UI Platform based on Angular-Material 2.0 +## Covalent: UI Platform based on Angular-Material 2 [![Build Status](https://travis-ci.org/Teradata/covalent.svg?branch=develop)](https://travis-ci.org/Teradata/covalent) [![npm version](https://badge.fury.io/js/%40covalent%2Fcore.svg)](https://badge.fury.io/js/%40covalent%2Fcore) @@ -13,18 +13,20 @@ Covalent is a reusable UI platform from Teradata for building web applications w ## Setup -* Ensure you have Node 4.4 and NPM 3+ installed. +* Ensure you have Node 5.5.0 - 6.9.1 and NPM 3+ installed. * Install Angular CLI `npm i -g angular-cli@latest` -* Install Typescript 2.0 `npm i -g typescript` +* Install Typescript 2.0.10 `npm i -g typescript@2.0.10` * Install TSLint `npm install -g tslint` * Install Protractor for e2e testing `npm install -g protractor` * Install Node packages `npm i` * Update Webdriver `webdriver-manager update` and `./node_modules/.bin/webdriver-manager update` -* Run local build `ng serve` +* Run local build `ng serve` or `ng serve --aot` --- +* [Getting Started](docs/GETTING_STARTED.md) * [Contributing Guidelines](docs/CONTRIBUTING.md) * [Developer Guide](docs/DEVELOPER_GUIDE.md) * [Releasing](docs/RELEASE.md) * [Changelog](docs/CHANGELOG.md) +* [Quickstart Repo](https://github.com/teradata/covalent-quickstart) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a4e65bd868..fbb7c87276 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -4,6 +4,7 @@ Make sure you have setup your environment based on the [Developer Guide](DEVELOP ### Development Guidelines +* **Always ask before creating a PR.** To avoid duplication efforts, its better to discuss it with us first or create an issue. * **All code must be reviewed via a pull request.** Before anything can be merged, it must be reviewed by at least 2 others. * ** Use git flow processes.** Start a feature, release, or hotfix branch, and you should never commit and push directly to `master` or `develop`. * **Squash commits into a single commit for your PR.** We want to keep a clean git history. diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md index 02b2ee40a5..649cd9cfaf 100644 --- a/docs/DEVELOPER_GUIDE.md +++ b/docs/DEVELOPER_GUIDE.md @@ -13,7 +13,7 @@ The source has two parts, the platform and a documentation app. /src/platform - Contains the platform assets ``` -## Adding a new platform component +## Adding a new platform module Add a new directory based on the name to `src/platform/[name]` and it should contain a folder structure that has the following: @@ -25,8 +25,6 @@ Add a new directory based on the name to `src/platform/[name]` and it should con * `package.json` - configurations used for npm to publish it (name[@covalent/name], version, dependencies, etc) * `README.md` - readme file with documentation for github and npm registry. -Then you will need to add a path `src/system-config.ts` under the library barrels that points to your new component directory, such as `'platform/[name]',`. - ## Adding a new documentation component You can use the `ng generate component components/[name]` and it will generate the new component stub in `src/app/components/[name]`. diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md new file mode 100644 index 0000000000..63c5234e2e --- /dev/null +++ b/docs/GETTING_STARTED.md @@ -0,0 +1,134 @@ +Get started with Covalent using the Angular CLI. + +See the [material2 getting started](https://github.com/angular/material2/blob/master/guides/getting-started.md) for instructions. + +## Install the CLI + + ```bash + npm install -g angular-cli + ``` + +## Create a new project + + ```bash + ng new my-project + ``` + +The new command creates a project with a build system for your Angular app. + +## Install Covalent Core module + +```bash +npm install --save @covalent/core +## (optional) Additional Covalent Modules installs +npm install --save @covalent/http @covalent/highlight @covalent/markdown @covalent/dynamic-forms +``` + +## Import the Covalent Core NgModule + +**src/app/app.module.ts** +```ts +import { CovalentCoreModule } from '@covalent/core'; +// (optional) Additional Covalent Modules imports +import { CovalentHttpModule } from '@covalent/http'; +import { CovalentHighlightModule } from '@covalent/highlight'; +import { CovalentMarkdownModule } from '@covalent/markdown'; +import { CovalentDynamicFormsModule } from '@covalent/dynamic-forms'; +// other imports +@NgModule({ + imports: [ + CovalentCoreModule.forRoot(), + // (optional) Additional Covalent Modules imports + CovalentHttpModule.forRoot(), + CovalentHighlightModule.forRoot(), + CovalentMarkdownModule.forRoot(), + CovalentDynamicFormsModule.forRoot(), + ], + ... +}) +export class AppModule { } +``` + +## Include the core and theme styles: +This is **required** to apply all of the core and theme styles to your application. + +See the [material2 theming guide](https://github.com/angular/material2/blob/master/guides/theming.md) for instructions. + +A theme file is a simple Sass file that defines your palettes and passes them to mixins that output the corresponding styles. A typical theme file will look something like this: + +```css +@import '~@angular/material/core/theming/all-theme'; +@import '~@covalent/core/theming/all-theme'; + +// (optional) Additional themes +@import '~@covalent/markdown/markdown-theme'; +@import '~@covalent/highlight/highlight-theme';\ + +@include md-core(); + +$primary: md-palette($md-orange, 800); +$accent: md-palette($md-light-blue, 600, A100, A400); + +$warn: md-palette($md-red, 600); + +$theme: md-light-theme($primary, $accent, $warn); + +@include angular-material-theme($theme); +@include covalent-theme($theme); + +// (optional) Additional themes +@include covalent-markdown-theme($theme); +@include covalent-highlight-theme(); +``` + +You only need this single Sass file; you do not need to use Sass to style the rest of your app. + +If you are using the Angular CLI, support for compiling Sass to css is built-in; you only have to add a new entry to the "styles" list in angular-cli.json pointing to the theme file (e.g., themes.scss). + +If you're not using the Angular CLI, you can use any existing Sass tooling to build the file (such as gulp-sass or grunt-sass). The simplest approach is to use the node-sass CLI; you simply run: + +node-sass src/themes.scss dist/themes.css +and then include the output file in your application. + +The theme file can be concatenated and minified with the rest of the application's css. + +## Configuring SystemJS +If your project is using SystemJS for module loading, you will need to add `@covalent/core` +to the SystemJS configuration: + +```js +System.config({ + // existing configuration options + map: { + ..., + '@covalent/core': 'npm:@covalent/core/core.umd.js', + // (optional) Additional configuration options + '@covalent/http': 'npm:@covalent/http/http.umd.js', + '@covalent/highlight': 'npm:@covalent/highlight/highlight.umd.js', + '@covalent/markdown': 'npm:@covalent/markdown/markdown.umd.js', + '@covalent/dynamic-forms': 'npm:@covalent/dynamic-forms/dynamic-forms.umd.js' + } +}); +``` + +### Using platform.scss: + +- The core covalent styles need to be included either in your `index.html` or as a new entry to the "styles" list in angular-cli.json +load the Material Design font in your `index.html`. + +**src/index.html** +```html + +``` + +or + +**angular-cli.json** +```json +"styles": [ + "../node_modules/@covalent/core/common/platform.scss" +], +``` + +## Sample Covalent projects +- [Covalent Quickstart](https://github.com/Teradata/covalent-quickstart) \ No newline at end of file