From 04594be89888d6e8d3a4046b8a3fc0c6906c10c5 Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 11:28:42 +0200 Subject: [PATCH 1/9] Move development related information to DEVELOPMENT.md from README --- DEVELOPMENT.md | 43 +++++++++++++++++++++++++++++++++++++++++++ README.md | 40 +--------------------------------------- 2 files changed, 44 insertions(+), 39 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..240edbe8 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,43 @@ +# Development instructions + +### Running development server and watches + +The project contains a small demo stylesheet that can be used to develop the UI. +Start watching UI code changes in lib/app and build the app using the demo stylesheets: + + gulp dev + +Running the task also runs a small development server, and does the same as: + + gulp watch --source ./lib/app --output ./demo-output --config ./lib/app/styleguide_config.json + +### Running tests + + npm test + +### Coding convention + +This project follows AirBNB-ish 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. + +To be able to check during development, please + +* run `$ gulp jscs` +* use [JSCS editor plugins](https://github.com/jscs-dev/node-jscs#friendly-packages) +* use [pre-commit hook](https://github.com/SC5/sc5-configurations/tree/master/.githooks/pre-commit) + +## How to release + +1. Check that all the needed pull requests are merged +1. Make sure that your clone fetched all the tags which exist in the SC5 repo +1. Rebase your `master` branch against SC5 +1. Create `release/x.y.z` branch with the number of upcoming version and switch to it +1. Increment the package number in `package.json` +1. Run `gulp publish` +1. Check the `CHANGELOG.md` file. You can remove not needed items or rename them. +1. Commit changes +1. Make a pull request from your feature branch +1. Once your pull request is merged, rebase your `master` against SC5 again +1. Run `npm publish` +1. Create a versioning tag in GitHub. Insert the `CHANGELOG.md` content as a description of this versioning tag. diff --git a/README.md b/README.md index e1e68caa..a59995ba 100644 --- a/README.md +++ b/README.md @@ -289,42 +289,4 @@ The demo generates styleguide to `demo-output` directory. ## How to develop -Projects contains small demo stylesheet that can be used to develop the UI. -Start watching UI changes in lib/app and build the app using the demo stylesheets: - - gulp dev - -Running the task also runs a small development server, and does the same as: - - gulp watch --source ./lib/app --output ./demo-output --config ./lib/app/styleguide_config.json - -### Running tests - - npm test - -### Coding convention - -This project follows AirBNB-ish 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. - -To be able to check during development, please - -* run `$ gulp jscs` -* use [JSCS editor plugins](https://github.com/jscs-dev/node-jscs#friendly-packages) -* use [pre-commit hook](https://github.com/SC5/sc5-configurations/tree/master/.githooks/pre-commit) - -## How to release - -1. Check that all the needed pull requests are merged -1. Make sure that your clone fetched all the tags which exist in the SC5 repo -1. Rebase your `master` branch against SC5 -1. Create `feature/x.y.z` branch with the number of upcoming version and switch to it -1. Increment the package number in `package.json` -1. Run `gulp publish` -1. Check the `CHANGELOG.md` file. You can remove not needed items or rename them. -1. Commit changes -1. Make a pull request from your feature branch -1. Once your pull request is merged, rebase your `master` against SC5 again -1. Run `npm publish` -1. Create a versioning tag in GitHub. Insert the `CHANGELOG.md` content as a description of this versioning tag. +See [development instructions](DEVELOPMENT.md) From 79fb6472b43cba9cfb5b9cacfadf6d08d3442aaa Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 11:39:24 +0200 Subject: [PATCH 2/9] Add Table of Contents --- DEVELOPMENT.md | 4 ++++ README.md | 25 ++++++++++++++++++++----- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 240edbe8..ff1ad599 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -13,8 +13,12 @@ Running the task also runs a small development server, and does the same as: ### Running tests +Run all the tests and JSCS linting with + npm test +Node module tests are ran with Mocha, UI related tests with Karma & PhantomJS. + ### Coding convention This project follows AirBNB-ish JavaScript coding convention (with a few changes). It is tuned to use [JSCS]() as a code diff --git a/README.md b/README.md index a59995ba..04c35ef1 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,21 @@ Styleguide generator is a handy little tool that helps you generate good looking styleguides from stylesheets using KSS notation. Styleguide generator can be used via command line utility, gulp task or grunt task (needs grunt-gulp) with minimal effort. -## How to use +## Table of contents + +* [How to use](#how-to-use) + * [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) + * [Build options](#build-options) +* [Documenting syntax](#documenting-syntax) + * [Wrapper markup](#wrapper-markup) +* [Designer tool](#designer-tool) +* [Demo](#demo) +* [Development instructions](#development-instructions) + +## How to Use 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. @@ -129,7 +143,7 @@ Then you are able to use the same gulp task inside you `Gruntfile`: For more specific documentation. See next section. -### Build Options +### Build options The gulp function and configuration JSON accepts identically named parameters @@ -200,7 +214,8 @@ Note: When using templateUrl in directives, the template path is relative to sty Document your CSS components with [KSS](http://warpspire.com/kss/) -### Wrapper +### Wrapper markup + Sometimes your component examples need a wrapper. For example: * you need to show how to use `
  • ` element which works only with `
      ` container; * your component is not visible with white background; @@ -273,7 +288,7 @@ would produce `
      ` for `
      ` for the Child section. -## Desiger tools +## Designer tool When sassVariables is defined and styleguide is served with the built-in server, designer tool is also enabled. Designer tool is experimental feature that allow style variable editing in the browser and saving changed variables back to the source file. @@ -287,6 +302,6 @@ Note: If you installed styleguide by cloning repository directly instead of npm The demo generates styleguide to `demo-output` directory. -## How to develop +## Development instructions See [development instructions](DEVELOPMENT.md) From c9b88dcc71603809b0f237e4253dee1040378545 Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 11:53:32 +0200 Subject: [PATCH 3/9] Make wrapper markup example a bit easier to read --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 04c35ef1..b876f722 100644 --- a/README.md +++ b/README.md @@ -284,9 +284,20 @@ a KSS markup // Styleguide 1.1 ``` -would produce `
      ` for the Parent section and -`
      ` for the Child -section. +would produce a Parent section: + ``` +
      +
      +
      +``` +and a Child section: +``` +
      +
      + +
      +
      +``` ## Designer tool From ba44c5aef730eca9aa802d20984663f13dfac641 Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 12:00:20 +0200 Subject: [PATCH 4/9] Add link to localhost:3000 under demo section --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index b876f722..67aee139 100644 --- a/README.md +++ b/README.md @@ -313,6 +313,8 @@ Note: If you installed styleguide by cloning repository directly instead of npm The demo generates styleguide to `demo-output` directory. +Point your browser to + ## Development instructions See [development instructions](DEVELOPMENT.md) From 64280eac593279a9711dc86c10c54ed99b5b0d6a Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 12:46:24 +0200 Subject: [PATCH 5/9] Add anchors to headers when rendering markdown --- lib/modules/markdown.js | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/lib/modules/markdown.js b/lib/modules/markdown.js index 855314ff..976aa061 100644 --- a/lib/modules/markdown.js +++ b/lib/modules/markdown.js @@ -3,6 +3,10 @@ var marked = require('gulp-marked'), vfs = require('vinyl-fs'); +function dasherize(str) { + return str.replace(/\s/ig, '-').toLowerCase(); +} + module.exports = { getStream: function(filePath) { @@ -15,7 +19,7 @@ module.exports = { var renderer = {}; // Define custom renderers for markup blocks renderer.heading = function(text, level) { - return '' + text + ''; + return '' + text + ''; }; renderer.paragraph = function(text) { return '

      ' + text + '

      '; @@ -51,7 +55,7 @@ module.exports = { .replace(/>/g, '>') .replace(/"/g, '"') .replace(/'/g, '''); - } + }; if (this.options.highlight) { var out = this.options.highlight(code, lang); @@ -73,8 +77,8 @@ module.exports = { + '">' + (escaped ? code : htmlEscape(code, true)) + '\n\n'; - } + }; return renderer; } -} +}; From 6ad714707ae695643391712670df0e93d089c1ab Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 12:47:48 +0200 Subject: [PATCH 6/9] Add margin-top to .sg paragraphs --- lib/app/sass/app.scss | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/app/sass/app.scss b/lib/app/sass/app.scss index 5f05bc74..94ad511d 100644 --- a/lib/app/sass/app.scss +++ b/lib/app/sass/app.scss @@ -149,6 +149,7 @@ a.sg:active { } p.sg { + margin-top: 1.3em; margin-bottom: 1.3em; line-height: 1.5em; color: rgba(#333, 1); From c070f5f5764df6b8b10a1c4d2773aca8297cdb94 Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 12:48:14 +0200 Subject: [PATCH 7/9] Add style to make contents bold --- lib/app/sass/app.scss | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/lib/app/sass/app.scss b/lib/app/sass/app.scss index 94ad511d..74380c2d 100644 --- a/lib/app/sass/app.scss +++ b/lib/app/sass/app.scss @@ -166,6 +166,11 @@ li.sg { padding: 0.2em 0; } +.sg { + strong { + font-weight: 700; + } +} // Buttons // // Button styles used in the styleguide From 9bf0fc6711590037157dba1605333a44e449c483 Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 12:58:28 +0200 Subject: [PATCH 8/9] Remove link to development.md, small wording fixes --- README.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 67aee139..cc08cb61 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ used via command line utility, gulp task or grunt task (needs grunt-gulp) with m ## Table of contents -* [How to use](#how-to-use) +* [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) @@ -17,9 +17,8 @@ used via command line utility, gulp task or grunt task (needs grunt-gulp) with m * [Wrapper markup](#wrapper-markup) * [Designer tool](#designer-tool) * [Demo](#demo) -* [Development instructions](#development-instructions) -## How to Use +## 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. @@ -30,11 +29,11 @@ SC5 Styleguide provides additions to KSS syntax which you can learn [below](#use Styleline command line tool searches all *.css, *.scss and *.less files from source directory and generates stand-alone styleguide to output path. You can host styleguide files yourself with any HTTP server or start built-in web server. -To install as a global command line tool +Installing as a global command line tool npm install -g sc5-styleguide -How to use from command line +Using from the command line styleguide -s -o [-c ] [--server] [--watch] @@ -74,7 +73,7 @@ Config JSON file could contain following settings ] } -For more specific documentation. See [Build Options](#build-options) section. +For more specific documentation. See [Build options](#build-options) section. ### As a module in your project @@ -103,7 +102,7 @@ For more specific documentation. See [Build Options](#build-options) section. .pipe(gulp.dest("")); }); -For more specific documentation. See [Build Options](#build-options) section. +For more specific documentation. See [Build options](#build-options) section. ### With Grunt @@ -314,7 +313,3 @@ Note: If you installed styleguide by cloning repository directly instead of npm The demo generates styleguide to `demo-output` directory. Point your browser to - -## Development instructions - -See [development instructions](DEVELOPMENT.md) From 5ef5e8ce2abe0c5de8cf34121a99c9135432c832 Mon Sep 17 00:00:00 2001 From: Juuso Backman Date: Tue, 18 Nov 2014 13:01:22 +0200 Subject: [PATCH 9/9] Do not render links to travis or david --- lib/modules/markdown.js | 10 +++++++++- test/markdown.js | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/lib/modules/markdown.js b/lib/modules/markdown.js index 976aa061..6eb06421 100644 --- a/lib/modules/markdown.js +++ b/lib/modules/markdown.js @@ -1,7 +1,11 @@ 'use strict'; var marked = require('gulp-marked'), - vfs = require('vinyl-fs'); + vfs = require('vinyl-fs'), + excludeLinks = [ + 'https://travis-ci.org/SC5/sc5-styleguide', + 'https://david-dm.org/SC5/sc5-styleguide' + ]; function dasherize(str) { return str.replace(/\s/ig, '-').toLowerCase(); @@ -28,6 +32,10 @@ module.exports = { return '
    • ' + text + '
      • \n'; }; renderer.link = function(href, title, text) { + if (excludeLinks.indexOf(href) >= 0) { + return ''; + } + if (this.options.sanitize) { try { var prot = decodeURIComponent(unescape(href)) diff --git a/test/markdown.js b/test/markdown.js index 67753844..bc4fa6c7 100644 --- a/test/markdown.js +++ b/test/markdown.js @@ -6,6 +6,38 @@ var gulp = require('gulp'), describe('Markdown', function() { + describe('renderer', function() { + + var renderer, result; + + beforeEach(function() { + renderer = markdown.getRenderer(); + renderer.options = { + sanitize: true + }; + }); + + describe('link', function() { + + it('adds class .sg to tags', function() { + result = renderer.link('linkHref', 'title', 'link text'); + expect(result).to.eql('link text'); + }); + + it('excludes link to https://travis-ci.org/SC5/sc5-styleguide', function() { + result = renderer.link('https://travis-ci.org/SC5/sc5-styleguide'); + expect(result).to.eql(''); + }); + + it('excludes link to https://david-dm.org/SC5/sc5-styleguide', function() { + result = renderer.link('https://david-dm.org/SC5/sc5-styleguide'); + expect(result).to.eql(''); + }); + + }); + + }); + it('getRenderer if formed correctly', function() { var renderer = markdown.getRenderer(); expect(renderer).to.be.an('object');