Merge pull request #426 from SC5/dev

Release 0.3.0
SC5 · Jan 20, 2015 · e0f99af · e0f99af
2 parents e9486e0 + 7a9050c
commit e0f99af
Show file tree

Hide file tree

Showing 29 changed files with 378 additions and 685 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,6 @@
-## 0.2.19 (2015-01-19)
+## 0.3.0 (2015-01-20)
 
 ### Features
-* Add variable syntax checking on save and show error on UI (#[412](https://github.com/SC5/sc5-styleguide/pull/412))
 
-### Fixes
-* Ensure variables' order in the Designer Tool is the same as in the source file (#[419](https://github.com/SC5/sc5-styleguide/pull/419))
-* Fix running `npm run demo` when parent project already has gulp as dependency (#[414](https://github.com/SC5/sc5-styleguide/pull/414))
+* *Breaking change:* Remove internal style preprocessing (#[Merge pull request #386](https://github.com/SC5/sc5-styleguide/pull/386))
+  * Since style preprocessing is not anymore part of the styleguide, it is now possible to use your preferred preprocessor. See README for the new API documentation.
diff --git a/README.md b/README.md
@@ -8,9 +8,8 @@ using KSS notation. It can be used as a command line utility, gulp task or grunt
 
 * [Usage](#usage)
   * [As a command line tool](#as-a-command-line-tool)
-  * [As a module in your project](#as-a-module-in-your-project)
-  * [With Gulp](#with-gulp)
-  * [With Grunt](#with-grunt)
+  * [With gulp](#with-gulp)
+  * [With grunt](#with-grunt)
   * [Build options](#build-options)
 * [Documenting syntax](#documenting-syntax)
   * [Wrapper markup](#wrapper-markup)
@@ -27,102 +26,82 @@ SC5 Style guide provides additions to KSS syntax which you can learn [below](#us
 
 ### As a command line tool
 
-Styleline command line tool searches all \*.css, \*.scss and \*.less files from source directory and generates
-a stand-alone style guide to output path. You can host the style guide files yourself with any HTTP server,
-or use the built-in web server.
-
-Installing as a global command line tool
+Install plugin globally:
 
     npm install -g sc5-styleguide
 
-Using from the command line
-
-    styleguide -s <source_path> -o <output_path> [-c <config_file>] [--server] [--watch]
-
-**-s, --source**
-
-Source directory of style sheets or path to a single file
-
-**-o, --output**
-
-Target directory of the generated style guide
-
-**-c, --config**
-
-Optional JSON config file to be used when building the style guide
-
-**--server**
-
-Start minimal web-server to host the style guide from the output directory
+Styleguide command line tool required two sets of source files:
 
-**--port**
+`--kss-source`: Unprocessed files containing the KSS markup and LESS/SASS variables
 
-Port in which the server will run
+`--style-source` Preprosessed/compiled stylesheets to be used in the styleguide
 
-**--watch**
+Example usage:
 
-Automatically generate style guide on file change. `--watch` does not run server. Combile with `--server` if you want to run server
+    styleguide --kss-source "sass/*.scss" --style-source "public/*.css" --output styleguide --watch --server
 
+Other options parameters are defined in the [Build options](#build-options) section.
 
-Config JSON file could look like following:
+### With gulp
 
-    {
-        title: "My Style guide",
-        "overviewPath": "<path to your overview.md>",
-        "extraHead": [
-            "<link rel=\"stylesheet\" type=\"text/css\" href=\"your/external/fonts/etc.css\">",
-            "<script src=\"your/custom/script.js\"></script>"
-        ],
-          sass: {
-            src: 'customSassSrc.sass'
-            // Other options passed to gulp-sass
-          },
-          less: {
-            src: 'customLessSrc.less'
-            // Other options passed to gulp-less
-          }
-    }
+Install plugin locally:
 
-For more specific documentation. See [Build options](#build-options) section.
+    npm install sc5-styleguide --save-dev
 
-### As a module in your project
+The gulp plugin contains two functions that requires different set of file streams:
 
-    npm install sc5-styleguide --save-dev
+`generate()`: All unprocessed styles containing the KSS markup and style variables. This will process the KSS markup and collects variable information.
 
-### With Gulp
+`applyStyles()`: Preprocessed/compiled stylesheets. This will create necessary pseudo styles and create the actual stylesheet to be used in the styleguide.
 
-    var styleguide = require("sc5-styleguide");
+The following code shows complete example how to use styleguide with gulp-sass and with gulp watch.
 
-    gulp.task("styleguide", function() {
-      var outputPath = '<destination folder>';
+    var styleguide = require('sc5-styleguide');
+    var sass = require('gulp-sass'),
+    var outputPath = 'output';
 
-      return gulp.src(["**/*.css", "**/*.scss", "**/*.less"])
-        .pipe(styleguide({
-            title: "My Styleguide",
+    gulp.task('styleguide:generate', function() {
+      return gulp.src('*.scss')
+        .pipe(styleguide.generate({
+            title: 'My Styleguide',
             server: true,
             rootPath: outputPath,
-            overviewPath: "<path to your overview.md>",
-            sass: {
-                // Options passed to gulp-sass
-            },
-            less: {
-                // Options passed to gulp-less
-            }
+            overviewPath: 'README.md',
+            styleVariables: 'lib/app/sass/_styleguide_variables.scss'
           }))
         .pipe(gulp.dest(outputPath));
     });
 
-    gulp.task("styleguide-watch", ["styleguide"], function() {
+    gulp.task('styleguide:applystyles', function() {
+      return gulp.src('main.scss')
+        .pipe(sass({
+          errLogToConsole: true
+        }))
+        .pipe(styleguide.applyStyles())
+        .pipe(gulp.dest(outputPath));
+    });
+
+    gulp.task('watch', ['styleguide'], function() {
       // Start watching changes and update styleguide whenever changes are detected
       // Styleguide automatically detects existing server instance
-      gulp.watch(["**/*.css", "**/*.scss", "**/*.less"], ["styleguide"]);
+      gulp.watch(['*.scss'], ['styleguide']);
     });
 
-For more specific documentation. See [Build options](#build-options) section.
+    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.
+
+If you do not use preprocessor you can directly pipe CSS files to `applyStyles()`.
 
-### With Grunt
+See [Build options](#build-options) section for complete documentation of different options.
 
-For Grunt-using projects you need to use `grunt-gulp` bridge:
+### With grunt
+
+Install the plugin first:
+
+    npm install sc5-styleguide --save-dev
+
+For Grunt-using projects you need also `grunt-gulp` bridge:
 
     npm install grunt-gulp --save-dev
 
@@ -134,35 +113,42 @@ Then you are able to use the same gulp task inside you `Gruntfile`:
     grunt.initConfig({
       pkg: grunt.file.readJSON('package.json'),
       gulp: {
-        styleguide: function() {
-          var outputPath = '<destination folder>';
-          return gulp.src(["**/*.css", "**/*.scss", "**/*.less"])
-            .pipe(styleguide({
-                title: "My Styleguide",
+        'styleguide-generate': function() {
+          var outputPath = 'output';
+          return gulp.src([''])
+            .pipe(styleguide.generate({
+                title: 'My Styleguide',
                 server: true,
                 rootPath: outputPath,
-                overviewPath: "<path to your overview.md>",
-                sass: {
-                    // Options passed to gulp-sass
-                },
-                less: {
-                    // Options passed to gulp-less
-                }
               }))
             .pipe(gulp.dest(outputPath));
+        },
+        'styleguide-applystyles': function() {
+          gulp.src(main.css)
+            .pipe(styleguide.applyStyles())
+            .pipe(gulp.dest(output)
+        }
+      }
+      watch: {
+        scss: {
+          files: '**/*.scss',
+          tasks: ['scss', 'gulp:styleguide-generate', 'gulp:styleguide-applystyles']
         }
       }
     });
 
     grunt.loadNpmTasks('grunt-gulp');
 
-    grunt.registerTask('default', ['gulp']);
+    grunt.registerTask('default', ['scss', 'gulp:styleguide-generate', 'gulp:styleguide-applystyles']);
+
+When using Grunt, we recommend to process styles in grunt tasks as you do for your main application and pass
+the resultant CSS into styleguide's gulp tasks.
 
 For more specific documentation. See next section.
 
 ### Build options
 
-The gulp function and configuration JSON accepts identically named parameters
+CLI and gulp otpions accepts identically named parameters
 
 <a name="option-title"></a>
 **title** (string, optional)
@@ -174,26 +160,6 @@ This string is used as a page title and in the page header
 
 These HTML elements are injected inside the style guide head-tag.
 
-<a name="option-sass"></a>
-**sass** (object, optional)
-
-Options passed to gulp-sass.
-Use `sass.src` to define which files are passed to the sass compiler.
-By default the gulp.src'ed files are filtered with `**/*.scss`.
-
-<a name="option-less"></a>
-**less** (object, optional)
-
-Options passed to gulp-less.
-Use `less.src` to define which files are passed to the less compiler.
-By default the gulp.src'ed files are filtered with `**/*.less`.
-
-<a name="option-css"></a>
-**css** (object, optional)
-
-Use `css.src` to define which css files will be included with the sass and less files.
-By default the gulp.src'ed files are filtered with `**/*.css`.
-
 <a name="option-commonClass"></a>
 **commonClass** (string or array of strings, optional)
 
@@ -217,6 +183,8 @@ Port of the server. Default is 3000.
 Server root path. This must be defined if you run the built-in server via gulp or grunt task.
 Point to the same path as the style guide output folder.
 
+Note: This option is not needed when running styleguide via the CLI.
+
 <a name="option-appRoot"></a>
 **appRoot** (string, optional)
 
@@ -400,29 +368,6 @@ Since each component's markup is isolated from the application styles with Shado
 also be used in the component previews, define a css class with the font definitions and add that class to the
 [commonClass configuration option](#option-commonClass).
 
-### How to exclude styles from styleguide
-
-All gulp src streams passed to the styleguide generator goes trought the flow that is much slower than normal style preprocessing. This could induce performance issues. If you have vendor styles in a subfolder, it is recommended to exclude them from build and pass only files that contains KSS markup as a gulp source stream. Use gulp `!` source syntax and declare the main source file as `sass` (or `less`) `src` option:
-
-    var styleguide = require("sc5-styleguide");
-
-    gulp.task("styleguide", function() {
-      return gulp.src([
-        "styles/**/*.less",
-        "!styles/bootsrap/**"
-        ]).pipe(styleguide({
-
-          ...
-
-          sass: {
-              src: '<main SASS file>'
-          },
-          less: {
-              src: '<main LESS file>'
-          }
-        ))
-    });
-
 ## Demo
 
 Build demo style guide and start a server on port 3000

diff --git a/bower.json b/bower.json
@@ -10,7 +10,8 @@
     "angular-local-storage": "0.1.0",
     "ui-router": "0.2.11",
     "oclazyload": "0.3.8",
-    "ngprogress": "~1.0.7"
+    "ngprogress": "~1.0.7",
+    "angular-debounce": "~1.0.0"
   },
   "devDependencies": {},
   "resolutions": {

diff --git a/demo-gulpfile.js b/demo-gulpfile.js
@@ -1,28 +1,35 @@
 var gulp = require('gulp'),
+  sass = require('gulp-sass'),
+  neat = require('node-neat'),
   styleguide = require('./lib/styleguide'),
   source = 'lib/app/**/*.scss',
   outputPath = 'demo-output';
 
-gulp.task('styleguide', ['static'], function() {
+gulp.task('styleguide:generate', function() {
   return gulp.src(source)
-    .pipe(styleguide({
+    .pipe(styleguide.generate({
         title: 'SC5 Styleguide',
         server: true,
         rootPath: outputPath,
         overviewPath: 'README.md',
-        styleVariables: 'lib/app/sass/_styleguide_variables.scss',
-        sass: {
-          src: 'lib/app/sass/app.scss',
-          includePaths: [
-            'node_modules/node-bourbon/assets/stylesheets',
-            'node_modules/node-neat/assets/stylesheets'
-          ]
-        }
+        styleVariables: 'lib/app/sass/_styleguide_variables.scss'
       }))
     .pipe(gulp.dest(outputPath));
 });
 
-gulp.task('static', function() {
+gulp.task('styleguide:applystyles', function() {
+  return gulp.src('lib/app/sass/app.scss')
+    .pipe(sass({
+      errLogToConsole: true,
+      includePaths: neat.includePaths
+    }))
+    .pipe(styleguide.applyStyles())
+    .pipe(gulp.dest(outputPath));
+});
+
+gulp.task('styleguide', ['styleguide:static', 'styleguide:generate', 'styleguide:applystyles']);
+
+gulp.task('styleguide:static', function() {
   gulp.src(['lib/demo/**'])
     .pipe(gulp.dest(outputPath + '/demo'));
 });