diff --git a/.yaspellerrc b/.yaspellerrc index d7ad7a32..26b3e5d2 100644 --- a/.yaspellerrc +++ b/.yaspellerrc @@ -41,12 +41,11 @@ "GitHub", "Travis", "PhantomJS", - "AirBNB", + "Airbnb", "JSCS", "linting", "npm", "rootPath", - "SASS", "onRendered", "src", "visualtest", diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a06275e5..f47f79c1 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,37 +1,47 @@ # Development instructions -### Branches -The project is developed in `master` branch. New feature or fix should come with a pull request from a fork. You can make a -pull request from either your `master` branch or from a feature branch. +## Branches + +The project is developed in `master` branch. +New feature or fix should come with a pull request from a fork. +You can make a pull request from either your `master` branch or from a feature branch. Developing the next major version goes in a separate branch made from `master`. -### Running development server and watches +## Running development server and watches -Your gulp needs to be at least v.3.9.0 +Your Gulp needs to be at least v.3.9.0 -Install all npm dependencies +Install all npm dependencies: - npm install +```sh +npm install +``` The style sheet of the style guide itself could be used as test data. Start watching UI code changes in lib/app and build the app using the style guides style sheets: - gulp dev +```sh +gulp dev +``` -### Running tests +## Running tests Run all the tests and JSCS linting with - npm test +```sh +npm test +``` Node module tests are ran with Mocha, UI related tests with Karma & PhantomJS. -### Coding convention +## Coding convention -This project follows AirBNB JavaScript coding convention (with a few changes). It is tuned to use [JSCS]() as a code -checker. The checking is injected into the testing process, so you can see in Travis respond to your pull-request if your -files follow the convention. +This project follows Airbnb [JavaScript coding convention](https://github.com/airbnb/javascript) (with a few changes). +It is tuned to use [JSCS](http://jscs.info/) as a code checker. +The checking is injected into the testing process, +so you can see in Travis respond to your pull-request +if your files follow the convention. To be able to check during development, please @@ -62,12 +72,12 @@ To be able to check during development, please Ton run the development server: -``` +```sh gulp website ``` To deploy server to production: -``` -website:deploy +```sh +gulp website:deploy ``` diff --git a/README.md b/README.md index 4a32f883..4ecfe778 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # SC5 style guide generator -[![Build Status](https://travis-ci.org/SC5/sc5-styleguide.svg?branch=master)](https://travis-ci.org/SC5/sc5-styleguide) [![dependencies](https://david-dm.org/SC5/sc5-styleguide.svg)](https://david-dm.org/SC5/sc5-styleguide) [![npm version](https://badge.fury.io/js/sc5-styleguide.svg)](http://badge.fury.io/js/sc5-styleguide) +[![Build Status](https://travis-ci.org/SC5/sc5-styleguide.svg?branch=master)](https://travis-ci.org/SC5/sc5-styleguide) [![dependencies](https://david-dm.org/SC5/sc5-styleguide.svg)](https://david-dm.org/SC5/sc5-styleguide) [![npm version](https://badge.fury.io/js/sc5-styleguide.svg)](http://badge.fury.io/js/sc5-styleguide) Style guide generator is a handy little tool that helps you generate good looking style guides from style sheets using KSS notation. It can be used as a command line utility, gulp task or Grunt task (needs grunt-gulp) with minimal effort. @@ -13,13 +13,13 @@ using KSS notation. It can be used as a command line utility, gulp task or Grunt - [Usage](#usage) - [Prerequisites](#prerequisites) - - [With gulp](#with-gulp) + - [With Gulp](#with-gulp) - [With Grunt](#with-grunt) - [As a command line tool](#as-a-command-line-tool) - [Build options](#build-options) - [Documenting syntax](#documenting-syntax) - [Defining an Angular directive](#defining-an-angular-directive) - - [Ignore parts of the style sheet from being processed](#ignore-parts-of-the-stylesheet-from-being-processed) + - [Ignore parts of the style sheet from being processed](#ignore-parts-of-the-style-sheet-from-being-processed) - [Wrapper markup](#wrapper-markup) - [Inserted markup](#inserted-markup) - [Pug (jade) markup](#pug-jade-markup) @@ -40,7 +40,6 @@ using KSS notation. It can be used as a command line utility, gulp task or Grunt ## Usage - You should familiarize yourself with both [KSS](https://github.com/kneath/kss) and [node-kss](https://github.com/kss-node/kss-node) to get yourself started. @@ -50,10 +49,10 @@ SC5 Style guide provides additions to KSS syntax which you can learn [below](#us The tool should be installed onto: -- node 0.12.x -- node 4.2.x +- Node 4.2.x +- Node 6.9.x -### With gulp +### With Gulp Install plugin locally: @@ -61,7 +60,7 @@ Install plugin locally: npm install sc5-styleguide --save-dev ``` -The gulp plugin contains two functions that requires different set of file streams: +The Gulp plugin contains two functions that requires different set of file streams: `generate()`: All unprocessed styles containing the KSS markup and style variables. This will process the KSS markup and collects variable information. @@ -104,7 +103,7 @@ gulp.task('watch', ['styleguide'], function() { gulp.task('styleguide', ['styleguide:generate', 'styleguide:applystyles']); ``` -This approach gives flexibility to use any preprocessor. For example, you can freely replace gulp-sass with gulp-ruby-sass. However, please notice that variable parsing works only for SASS, SCSS and LESS files. +This approach gives flexibility to use any preprocessor. For example, you can freely replace gulp-sass with gulp-ruby-sass. However, please notice that variable parsing works only for Sass, SCSS and Less files. If you do not use preprocessor you can directly pipe CSS files to `applyStyles()`. @@ -112,7 +111,7 @@ See [Build options](#build-options) section for complete documentation of differ ### With Grunt -For projects using Grunt, install the plugin, gulp and the `grunt-gulp` bridge. +For projects using Grunt, install the plugin, Gulp and the `grunt-gulp` bridge. ```bash npm install sc5-styleguide gulp grunt-gulp --save-dev @@ -159,13 +158,13 @@ grunt.registerTask('default', ['gulp:styleguide-generate', 'gulp:styleguide-appl ``` When using Grunt, we recommend processing styles in Grunt tasks as you do for your main application and pass -the resultant CSS into styleguide's gulp tasks. +the resultant CSS into styleguide's Gulp tasks. For more specific documentation see the next section. ### As a command line tool -This way is less recommended as it less helps with introducing the styleguide into the day-to-day process. +This way of usage is not recommended, as it does not help as much with introduction of the styleguide into the day-to-day development process. Install plugin globally: @@ -175,7 +174,7 @@ npm install -g sc5-styleguide Styleguide command line tool requires two sets of source files: -`--kss-source`: Unprocessed files containing the KSS markup and LESS/SASS variables +`--kss-source`: Unprocessed files containing the KSS markup and Less/Sass variables `--style-source` Pre-processed/compiled style sheets to be used in the styleguide @@ -235,7 +234,7 @@ Show/hide Markup section. **hideSubsectionsOnMainSection** (boolean, optional, default: false) -This option enables to prevent loading of subsections. +This option enables to prevent loading of subsections. **beforeBody** (array or string, optional) @@ -337,6 +336,7 @@ You can define your own styles with /* Define your styles here */ } ``` + PostCSS configuration supports mixins, nesting, variables, media queries. @@ -505,9 +505,10 @@ Ignored styles ### Wrapper markup Sometimes your component examples need a wrapper. For example: -* you need to show how to use `
  • ` element which works only with `