New GitBook documentation

README.md

@@ -1,59 +1,50 @@
-# Defer initial chart updates
+<div align="center">
+    <img src="docs/assets/banner.png"/>
+</div>
 
-[![npm](https://img.shields.io/npm/v/chartjs-plugin-deferred.svg?style=flat-square)](https://npmjs.com/package/chartjs-plugin-deferred) [![bower](https://img.shields.io/bower/v/chartjs-plugin-deferred.svg?style=flat-square)](https://libraries.io/bower/chartjs-plugin-deferred) [![travis](https://img.shields.io/travis/chartjs/chartjs-plugin-deferred.svg?style=flat-square)](https://travis-ci.org/chartjs/chartjs-plugin-deferred) [![codeclimate](https://img.shields.io/codeclimate/maintainability/chartjs/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://codeclimate.com/github/chartjs/chartjs-plugin-deferred)
+[![github](https://img.shields.io/github/release/chartjs/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://github.com/chartjs/chartjs-plugin-deferred/releases/latest) [![travis](https://img.shields.io/travis/chartjs/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://travis-ci.org/chartjs/chartjs-plugin-deferred) [![codeclimate](https://img.shields.io/codeclimate/maintainability/chartjs/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://codeclimate.com/github/chartjs/chartjs-plugin-deferred)
 
 [Chart.js](http://www.chartjs.org/) plugin to defer initial chart updates until the user scrolls and the canvas appears inside the viewport, and thus trigger the initial chart animations when the user is likely to see them.
 
 Requires [Chart.js](https://github.com/chartjs/Chart.js/releases) **2.6.0** or later.
 
-## Usage
+## Documentation
 
-You can download the latest version of [chartjs-plugin-deferred on GitHub](https://github.com/chartjs/chartjs-plugin-deferred/releases/latest)
+- [Installation](https://chartjs-plugin-deferred.netlify.com/installation)
+- [Options](https://chartjs-plugin-deferred.netlify.com/options)
 
-## Configuration
+## Example
 
-To configure this plugin, you can simply add the following entries to your chart options:
-
-| Name | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| `plugins.deferred` | `Object/Boolean` | `true` | The deferred options (see `plugins.deferred.*` options). Also accepts a boolean, in which case if `true`, the chart will be deferred using the **global options**, else if `false`, the chart will not be deferred.
-| `plugins.deferred.xOffset` | `Number/String` | `0` | Number of pixels (or percent of the canvas width) from which the chart is considered inside the viewport.
-| `plugins.deferred.yOffset` | `Number/String` | `0` | Number of pixels (or percent of the canvas height) from which the chart is considered inside the viewport.
-| `plugins.deferred.delay` | `Number` | `0` | Number of milliseconds to delay the loading after the chart is considered inside the viewport.
-
-> **Global options** can be change through `Chart.defaults.global.plugins.deferred`, which by default defer the chart loading until the first line of pixels of the canvas appears in the viewport.
-
-For example:
-
-```
-{
+```javascript
+new Chart(ctx, {
+  // ... data ...
+  options: {
+    // ... other options ...
     plugins: {
-        deferred: {           // enabled by default
-            xOffset: 150,     // defer until 150px of the canvas width are inside the viewport
-            yOffset: '50%',   // defer until 50% of the canvas height are inside the viewport
-            delay: 500        // delay of 500 ms after the canvas is considered inside the viewport
-        }
+      deferred: {
+        xOffset: 150,   // defer until 150px of the canvas width are inside the viewport
+        yOffset: '50%', // defer until 50% of the canvas height are inside the viewport
+        delay: 500      // delay of 500 ms after the canvas is considered inside the viewport
+      }
     }
-}
+  }
+});
 ```
 
 ## Development
 
 You first need to install node dependencies (requires [Node.js](https://nodejs.org/)):
 
-```shell
-> npm install
-```
+    > npm install
 
 The following commands will then be available from the repository root:
 
-```shell
-> gulp build            // build dist files
-> gulp build --watch    // build and watch for changes
-> gulp lint             // perform code linting
-> gulp package          // create an archive with dist files and samples
-```
+    > gulp build            // build dist files
+    > gulp build --watch    // build and watch for changes
+    > gulp lint             // perform code linting
+    > gulp docs             // generate GitBook documentation (`dist/docs`)
+    > gulp package          // create an archive with dist files and samples
 
 ## License
 
-chartjs-plugin-deferred is available under the [MIT license](LICENSE.md).
+`chartjs-plugin-deferred` is available under the [MIT license](LICENSE.md).

book.json

@@ -0,0 +1,29 @@
+{
+	"root": "docs",
+	"author": "chartjs",
+	"gitbook": "3.2.2",
+	"plugins": [
+		"-lunr",
+		"-search",
+		"search-plus",
+		"anchorjs",
+		"ga"
+	],
+	"pluginsConfig": {
+		"anchorjs": {
+			"icon": "#",
+			"placement": "left",
+			"visible": "always"
+		},
+		"ga": {
+			"token": "UA-99068522-3",
+			"configuration": "auto"
+		},
+		"theme-default": {
+			"showLevel": false,
+			"styles": {
+				"website": "assets/style.css"
+			}
+		}
+	}
+}

docs/README.md

@@ -0,0 +1,31 @@
+![chartjs-plugin-deferred](assets/banner.png)
+
+[Chart.js](http://www.chartjs.org/) plugin to defer initial chart updates until the user scrolls and the canvas appears inside the viewport, and thus trigger the initial chart animations when the user is likely to see them.
+
+**Important:** requires [Chart.js](https://github.com/chartjs/Chart.js/releases) **2.6.0** or later.
+
+## Table of Contents
+
+{% include "SUMMARY.md" %}
+
+## Example
+
+```javascript
+new Chart(ctx, {
+  // ... data ...
+  options: {
+    // ... other options ...
+    plugins: {
+      deferred: {
+        xOffset: 150,   // defer until 150px of the canvas width are inside the viewport
+        yOffset: '50%', // defer until 50% of the canvas height are inside the viewport
+        delay: 500      // delay of 500 ms after the canvas is considered inside the viewport
+      }
+    }
+  }
+});
+```
+
+## License
+
+`chartjs-plugin-deferred` is available under the [MIT license](https://github.com/chartjs/chartjs-plugin-deferred/blob/master/LICENSE.md).

docs/SUMMARY.md

@@ -0,0 +1,2 @@
+* [Installation](installation.md)
+* [Options](options.md)

docs/assets/style.css

@@ -0,0 +1,15 @@
+a.anchorjs-link {
+    color: rgba(65, 131, 196, 0.1);
+    font-weight: 400;
+    text-decoration: none;
+    transition: color 100ms ease-out;
+    z-index: 999;
+}
+
+a.anchorjs-link:hover {
+    color: rgba(65, 131, 196, 1);
+}
+
+sup {
+    font-size: 0.75em !important;
+}

docs/installation.md

@@ -0,0 +1,34 @@
+# Installation
+
+## npm
+
+[![npm](https://img.shields.io/npm/v/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://npmjs.com/package/chartjs-plugin-deferred) [![npm downloads](https://img.shields.io/npm/dm/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://npmjs.com/package/chartjs-plugin-deferred)
+
+    npm install chartjs-plugin-deferred --save
+
+## Bower
+
+[![bower](https://img.shields.io/bower/v/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://libraries.io/bower/chartjs-plugin-deferred)
+
+    bower install chartjs-plugin-deferred --save
+
+## CDN
+
+[![jsdelivr](https://img.shields.io/npm/v/chartjs-plugin-deferred.svg?label=jsdelivr&style=flat-square&maxAge=600)](https://cdn.jsdelivr.net/npm/chartjs-plugin-deferred@latest/dist/) [![jsdelivr hits](https://data.jsdelivr.com/v1/package/npm/chartjs-plugin-deferred/badge)](https://www.jsdelivr.com/package/npm/chartjs-plugin-deferred)
+
+By default, `https://cdn.jsdelivr.net/npm/chartjs-plugin-deferred` returns the latest (minified) version, however it's [**highly recommended**](https://www.jsdelivr.com/features) to always specify a version in order to avoid breaking changes. This can be achieved by appending `@{version}` to the url:
+
+    https://cdn.jsdelivr.net/npm/[email protected]    // exact version
+    https://cdn.jsdelivr.net/npm/chartjs-plugin-deferred@1        // latest 1.x.x
+
+Read more about jsDeliver versioning on their [website](http://www.jsdelivr.com/).
+
+## Download
+
+[![github](https://img.shields.io/github/release/chartjs/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://github.com/chartjs/chartjs-plugin-deferred/releases/latest) [![github downloads](https://img.shields.io/github/downloads/chartjs/chartjs-plugin-deferred/total.svg?style=flat-square&maxAge=600)](http://www.somsubhra.com/github-release-stats/?username=chartjs&repository=chartjs-plugin-deferred)
+
+You can download the latest version of `chartjs-plugin-deferred` from the [GitHub releases](https://github.com/chartjs/chartjs-plugin-deferred/releases/latest):
+
+- `chartjs-plugin-deferred.js` (recommended for development)
+- `chartjs-plugin-deferred.min.js` (recommended for production)
+- `chartjs-plugin-deferred.zip` (contains `.js` and `.min.js` versions + samples)

docs/options.md

@@ -0,0 +1,25 @@
+# Options
+
+The plugin options can be changed at 2 different levels and with the following priority:
+
+- per chart: `options.plugins.deferred.*`
+- globally: `Chart.defaults.global.plugins.deferred.*`
+
+Available options:
+
+| Name | Type | Default
+| ---- | ---- | ----
+| [`delay`](#delay) | `Number` | `0`
+| [`xOffset`](#xoffset) | `Number/String` | `0`
+| [`yOffset`](#yoffset) | `Number/String` | `0`
+
+> **Note:** default options defer the chart loading until the first line of pixels of the canvas appears in the viewport
+
+## `delay`
+Number of milliseconds to delay the loading after the chart is considered inside the viewport.
+
+## `xOffset`
+Number of pixels (or percent of the canvas width) from which the chart is considered inside the viewport.
+
+## `yOffset`
+Number of pixels (or percent of the canvas height) from which the chart is considered inside the viewport.

gulpfile.js

@@ -1,6 +1,5 @@
 'use strict';
 
-var argv = require('yargs').argv;
 var gulp = require('gulp');
 var eslint = require('gulp-eslint');
 var file = require('gulp-file');
@@ -14,11 +13,13 @@ var merge = require('merge2');
 var path = require('path');
 var rollup = require('rollup-stream');
 var source = require('vinyl-source-stream');
+var {exec} = require('mz/child_process');
 var pkg = require('./package.json');
 
-var srcDir = './src/';
-var outDir = './dist/';
-var samplesDir = './samples/';
+var argv = require('yargs')
+	.option('output', {alias: 'o', default: 'dist'})
+	.option('docs-dir', {default: 'docs'})
+	.argv;
 
 function watch(glob, task) {
 	gutil.log('Waiting for changes...');
@@ -33,27 +34,28 @@ function watch(glob, task) {
 gulp.task('default', ['build']);
 
 gulp.task('build', function() {
+	var out = argv.output;
 	var task = function() {
 		return rollup('rollup.config.js')
 			.pipe(source(pkg.name + '.js'))
-			.pipe(gulp.dest(outDir))
+			.pipe(gulp.dest(out))
 			.pipe(rename(pkg.name + '.min.js'))
 			.pipe(streamify(uglify({output: {comments: 'some'}})))
-			.pipe(gulp.dest(outDir));
+			.pipe(gulp.dest(out));
 	};
 
 	var tasks = [task()];
 	if (argv.watch) {
-		tasks.push(watch(srcDir + '**/*.js', task));
+		tasks.push(watch('src/**/*.js', task));
 	}
 
 	return tasks;
 });
 
 gulp.task('lint', function() {
 	var files = [
-		samplesDir + '**/*.js',
-		srcDir + '**/*.js',
+		'samples/**/*.js',
+		'src/**/*.js',
 		'*.js'
 	];
 
@@ -63,20 +65,35 @@ gulp.task('lint', function() {
 		.pipe(eslint.failAfterError());
 });
 
+gulp.task('docs', function(done) {
+	var script = require.resolve('gitbook-cli/bin/gitbook.js');
+	var out = path.join(argv.output, argv.docsDir);
+	var cmd = process.execPath;
+
+	exec([cmd, script, 'install', './'].join(' ')).then(() => {
+		return exec([cmd, script, 'build', './', out].join(' '));
+	}).then(() => {
+		done();
+	}).catch((err) => {
+		done(new Error(err.stdout || err));
+	});
+});
+
 gulp.task('package', function() {
+	var out = argv.output;
 	var streams = merge(
 		// gather "regular" files landing in the package root
-		gulp.src([outDir + '*.js', 'LICENSE.md']),
+		gulp.src([out + '*.js', 'LICENSE.md']),
 
 		// dist files in the package are in the root, so we need to rewrite samples
 		// src="../dist/ to src="../ and then copy them in the /samples directory.
-		gulp.src(samplesDir + '**/*', {base: '.'})
+		gulp.src('samples/**/*', {base: '.'})
 			.pipe(streamify(replace('src="../dist/', 'src="../')))
 	);
 
 	return streams
 		.pipe(zip(pkg.name + '.zip'))
-		.pipe(gulp.dest(outDir));
+		.pipe(gulp.dest(out));
 });
 
 gulp.task('bower', function() {
@@ -86,7 +103,7 @@ gulp.task('bower', function() {
 		homepage: pkg.homepage,
 		license: pkg.license,
 		version: pkg.version,
-		main: outDir + pkg.name + '.js'
+		main: argv.output + pkg.name + '.js'
 	}, null, 2);
 
 	return file('bower.json', json, {src: true})

package.json

@@ -11,6 +11,7 @@
   },
   "devDependencies": {
     "eslint-config-chartjs": "^0.1.0",
+    "gitbook-cli": "^2.3.2",
     "gulp": "^3.9.1",
     "gulp-eslint": "^4.0.1",
     "gulp-file": "^0.4.0",
@@ -21,6 +22,7 @@
     "gulp-util": "^3.0.7",
     "gulp-zip": "^4.1.0",
     "merge2": "^1.2.1",
+    "mz": "^2.7.0",
     "path": "^0.12.7",
     "rollup": "^0.53.4",
     "rollup-stream": "^1.24.1",