Rework the README to allow the examples to be validated.

.travis.yml

@@ -22,6 +22,9 @@ matrix:
     - name: Lint
       node_js: 14
       script: npm run lint
+    - name: Documentation
+      node_js: 14
+      script: npm run test:documentation
 
 script: '(nvm i 14 && npm run build) && npm run ci:test'
 after_success: '<coverage/lcov.info ./node_modules/coveralls/bin/coveralls.js'

README.md

@@ -1,4 +1,4 @@
-# one.color
+# onecolor
 
 [![NPM version](https://badge.fury.io/js/onecolor.svg)](http://badge.fury.io/js/onecolor)
 [![Build Status](https://travis-ci.org/One-com/one-color.svg?branch=master)](https://travis-ci.org/One-com/one-color)
@@ -49,20 +49,25 @@ named color support):
 </script>
 ```
 
-In node.js (after `npm install onecolor`):
+In the browser, the parser is exposed as a global named `onecolor`.
+In node.js, it is returned directly with a require of the module
+(after `npm install onecolor`):
 
 ```javascript
 var color = require('onecolor');
-console.warn(color('rgba(100%, 0%, 0%, .5)').alpha(0.4).cssa()); // 'rgba(255,0,0,0.4)'
+console.warn(color('rgba(100%, 0%, 0%, .5)').alpha(0.4).cssa());
 ```
 
-`one.color` is the parser. All of the above return color instances in
-the relevant color space with the channel values (0..1) as instance
-variables:
+```output
+'rgba(255,0,0,0.4)'
+```
+
+All of the above return color instances in the relevant color space
+with the channel values (0..1) as instance variables:
 
 ```javascript
-var myColor = one.color('#a9d91d');
-myColor instanceof one.color.RGB; // true
+var myColor = color('#a9d91d');
+myColor instanceof color.RGB; // true
 myColor.red(); // 0.6627450980392157
 ```
 
@@ -71,15 +76,15 @@ but the requires the slightly bigger <a href="//raw.github.com/One-com/one-color
 browser):
 
 ```javascript
-one.color('maroon').lightness(0.3).hex(); // '#990000'
+color('maroon').lightness(0.3).hex(); // '#990000'
 ```
 
 To turn a color instance back into a string, use the `hex()`, `css()`,
 and `cssa()` methods:
 
 ```javascript
-one.color('rgb(124, 96, 200)').hex(); // '#7c60c8'
-one.color('#bb7b81').cssa(); // 'rgba(187,123,129,1)'
+color('rgb(124, 96, 200)').hex(); // '#7c60c8'
+color('#bb7b81').cssa(); // 'rgba(187,123,129,1)'
 ```
 
 Color instances have getters/setters for all channels in all supported
@@ -88,8 +93,7 @@ colorspaces (`red()`, `green()`, `blue()`, `hue()`, `saturation()`, `lightness()
 you're in. All the necessary conversions happen automatically:
 
 ```javascript
-one
-  .color('#ff0000') // Red in RGB
+color('#ff0000') // Red in RGB
   .green(1) // Set green to the max value, producing yellow (still RGB)
   .hue(0.5, true) // Add 180 degrees to the hue, implicitly converting to HSV
   .hex(); // Dump as RGB hex syntax: '#2222ff'
@@ -99,15 +103,15 @@ When called without any arguments, they return the current value of
 the channel (0..1):
 
 ```javascript
-one.color('#09ffdd').green(); // 1
-one.color('#09ffdd').saturation(); // 0.9647058823529412
+color('#09ffdd').green(); // 1
+color('#09ffdd').saturation(); // 0.9647058823529412
 ```
 
 When called with a single numerical argument (0..1), a new color
 object is returned with that channel replaced:
 
 ```javascript
-var myColor = one.color('#00ddff');
+var myColor = color('#00ddff');
 myColor.red(0.5).red(); // .5
 
 // ... but as the objects are immutable, the original object retains its value:
@@ -119,8 +123,7 @@ the second argument, a new value is returned with that channel
 adjusted:
 
 ```javascript
-one
-  .color('#ff0000') // Red
+color('#ff0000') // Red
   .red(-0.1, true) // Adjust red channel by -0.1
   .hex(); // '#e60000'
 ```
@@ -133,7 +136,7 @@ All color instances have an alpha channel (0..1), defaulting to 1
 It's preserved when converting between colorspaces:
 
 ```javascript
-one.color('rgba(10, 20, 30, .8)').green(0.4).saturation(0.2).alpha(); // 0.8
+color('rgba(10, 20, 30, .8)').green(0.4).saturation(0.2).alpha(); // 0.8
 ```
 
 ## Comparing color objects
@@ -142,87 +145,93 @@ If you need to know whether two colors represent the same 8 bit color, regardles
 of colorspace, compare their `hex()` values:
 
 ```javascript
-one.color('#f00').hex() === one.color('#e00').red(1).hex(); // true
+color('#f00').hex() === color('#e00').red(1).hex(); // true
 ```
 
 Use the `equals` method to compare two color instances within a certain
 epsilon (defaults to `1e-9`).
 
 ```javascript
-one.color('#e00').lightness(0.00001, true).equals(one.color('#e00'), 1e-5); // false
-one.color('#e00').lightness(0.000001, true).equals(one.color('#e00'), 1e-5); // true
+color('#e00').lightness(0.00001, true).equals(color('#e00'), 1e-5); // false
+color('#e00').lightness(0.000001, true).equals(color('#e00'), 1e-5); // true
 ```
 
 Before comparing the `equals` method converts the other color to the right colorspace,
 so you don't need to convert explicitly in this case either:
 
 ```javascript
-one.color('#e00').hsv().equals(one.color('#e00')); // true
+color('#e00').hsv().equals(color('#e00')); // true
 ```
 
 # API overview
 
 Color parser function, the recommended way to create a color instance:
 
 ```javascript
-one.color('#a9d91d'); // Regular hex syntax
-one.color('a9d91d'); // hex syntax, # is optional
-one.color('#eee'); // Short hex syntax
-one.color('rgb(124, 96, 200)'); // CSS rgb syntax
-one.color('rgb(99%, 40%, 0%)'); // CSS rgb syntax with percentages
-one.color('rgba(124, 96, 200, .4)'); // CSS rgba syntax
-one.color('hsl(120, 75%, 75%)'); // CSS hsl syntax
-one.color('hsla(120, 75%, 75%, .1)'); // CSS hsla syntax
-one.color('hsv(220, 47%, 12%)'); // CSS hsv syntax (non-standard)
-one.color('hsva(120, 75%, 75%, 0)'); // CSS hsva syntax (non-standard)
-one.color([0, 4, 255, 120]); // CanvasPixelArray entry, RGBA
-one.color(['RGB', 0.5, 0.1, 0.6, 0.9]); // The output format of color.toJSON()
+color('#a9d91d'); // Regular hex syntax
+color('a9d91d'); // hex syntax, # is optional
+color('#eee'); // Short hex syntax
+color('rgb(124, 96, 200)'); // CSS rgb syntax
+color('rgb(99%, 40%, 0%)'); // CSS rgb syntax with percentages
+color('rgba(124, 96, 200, .4)'); // CSS rgba syntax
+color('hsl(120, 75%, 75%)'); // CSS hsl syntax
+color('hsla(120, 75%, 75%, .1)'); // CSS hsla syntax
+color('hsv(220, 47%, 12%)'); // CSS hsv syntax (non-standard)
+color('hsva(120, 75%, 75%, 0)'); // CSS hsva syntax (non-standard)
+color([0, 4, 255, 120]); // CanvasPixelArray entry, RGBA
+color(['RGB', 0.5, 0.1, 0.6, 0.9]); // The output format of color.toJSON()
 ```
 
 The slightly bigger <a href="//raw.github.com/One-com/one-color/master/one-color-all.js">one-color-all.js</a> build adds support for
 <a href='http://en.wikipedia.org/wiki/Web_colors'>the standard suite of named CSS colors</a>:
 
 ```javascript
-one.color('maroon');
-one.color('darkolivegreen');
+color('maroon');
+color('darkolivegreen');
 ```
 
-Existing one.color instances pass through unchanged, which is useful
+Existing onecolor instances pass through unchanged, which is useful
 in APIs where you want to accept either a string or a color instance:
 
 ```javascript
-one.color(one.color('#fff')); // Same as one.color('#fff')
+color(color('#fff')); // Same as color('#fff')
 ```
 
 Serialization methods:
 
 ```javascript
-color.hex(); // 6-digit hex string: '#bda65b'
-color.css(); // CSS rgb syntax: 'rgb(10,128,220)'
-color.cssa(); // CSS rgba syntax: 'rgba(10,128,220,0.8)'
-color.toString(); // For debugging: '[one.color.RGB: Red=0.3 Green=0.8 Blue=0 Alpha=1]'
-color.toJSON(); // ["RGB"|"HSV"|"HSL", <number>, <number>, <number>, <number>]
+var myColor = color('#bda65b');
+
+myColor.hex(); // 6-digit hex string: '#bda65b'
+myColor.css(); // CSS rgb syntax: 'rgb(10,128,220)'
+myColor.cssa(); // CSS rgba syntax: 'rgba(10,128,220,0.8)'
+myColor.toString(); // For debugging: '[onecolor.RGB: Red=0.3 Green=0.8 Blue=0 Alpha=1]'
+myColor.toJSON(); // ["RGB"|"HSV"|"HSL", <number>, <number>, <number>, <number>]
 ```
 
 Getters -- return the value of the channel (converts to other colorspaces as needed):
 
 ```javascript
-color.red();
-color.green();
-color.blue();
-color.hue();
-color.saturation();
-color.value();
-color.lightness();
-color.alpha();
-color.cyan(); // one-color-all.js and node.js only
-color.magenta(); // one-color-all.js and node.js only
-color.yellow(); // one-color-all.js and node.js only
-color.black(); // one-color-all.js and node.js only
+var myColor = color('#bda65b');
+
+myColor.red();
+myColor.green();
+myColor.blue();
+myColor.hue();
+myColor.saturation();
+myColor.value();
+myColor.lightness();
+myColor.alpha();
+myColor.cyan(); // one-color-all.js and node.js only
+myColor.magenta(); // one-color-all.js and node.js only
+myColor.yellow(); // one-color-all.js and node.js only
+myColor.black(); // one-color-all.js and node.js only
 ```
 
 Setters -- return new color instances with one channel changed:
 
+<!-- evaldown evaluate:false -->
+
 ```javascript
 color.red(<number>)
 color.green(<number>)
@@ -241,6 +250,8 @@ color.black(<number>)   // one-color-all.js and node.js only
 Adjusters -- return new color instances with the channel adjusted by
 the specified delta (0..1):
 
+<!-- evaldown evaluate:false -->
+
 ```javascript
 color.red(<number>, true)
 color.green(<number>, true)
@@ -258,6 +269,8 @@ color.black(<number>, true)   // one-color-all.js and node.js only
 
 Comparison with other color objects, returns `true` or `false` (epsilon defaults to `1e-9`):
 
+<!-- evaldown evaluate:false -->
+
 ```javascript
 color.equals(otherColor[, <epsilon>])
 ```
@@ -267,15 +280,15 @@ color.equals(otherColor[, <epsilon>])
 "Low level" constructors, accept 3 or 4 numerical arguments (0..1):
 
 ```javascript
-new one.color.RGB(<red>, <green>, <blue>[, <alpha>])
-new one.color.HSL(<hue>, <saturation>, <lightness>[, <alpha>])
-new one.color.HSV(<hue>, <saturation>, <value>[, <alpha>])
+new onecolor.RGB(<red>, <green>, <blue>[, <alpha>])
+new onecolor.HSL(<hue>, <saturation>, <lightness>[, <alpha>])
+new onecolor.HSV(<hue>, <saturation>, <value>[, <alpha>])
 ```
 
 The <a href="//raw.github.com/One-com/one-color/master/one-color-all.js">one-color-all.js</a> build includes CMYK support:
 
 ```javascript
-new one.color.CMYK(<cyan>, <magenta>, <yellow>, <black>[, <alpha>])
+new onecolor.CMYK(<cyan>, <magenta>, <yellow>, <black>[, <alpha>])
 ```
 
 All color instances have `rgb()`, `hsv()`, and `hsl()` methods for
@@ -288,12 +301,15 @@ specific colorspace, do an explicit conversion first to cut down on
 the number of implicit conversions:
 
 ```javascript
-var myColor = one
-  .color('#0620ff')
+var myColor = color('#0620ff')
   .lightness(+0.3)
   .rgb();
-// Alerts '0 0.06265060240963878 0.5999999999999999':
-alert(myColor.red() + ' ' + myColor.green() + ' ' + myColor.blue());
+
+console.log(myColor.red() + ' ' + myColor.green() + ' ' + myColor.blue());
+```
+
+```output
+'0 0.06265060240963878 0.5999999999999999'
 ```
 
 # Building
@@ -313,4 +329,4 @@ packages in the repository as well as the npm package:
 
 # License
 
-one.color is licensed under a standard 2-clause BSD license -- see the `LICENSE` file for details.
+onecolor is licensed under a standard 2-clause BSD license -- see the `LICENSE` file for details.

package.json

@@ -34,9 +34,11 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^4.2.1",
     "eslint-plugin-standard": "^4.0.1",
+    "evaldown": "^1.1.2",
     "istanbul": "0.4.2",
     "mocha": "2.4.5",
     "mocha-lcov-reporter": "1.2.0",
+    "onecolor": "file:./",
     "prettier": "^2.0.5",
     "rollup": "^2.21.0",
     "rollup-plugin-terser": "^6.1.0",
@@ -61,6 +63,7 @@
     "preversion": "npm run lint && npm run build && TEST_BUNDLES=true npm test && bash -c 'git add one-color{-all,}.{js,map}'",
     "lint": "eslint . && prettier --check '**/*.{js,md}'",
     "test": "npm run lint && mocha",
+    "test:documentation": "evaldown --validate --capture=console ./README.md",
     "coverage": "istanbul cover _mocha -- --reporter dot",
     "ci:test": "TEST_BUNDLES=true npm run coverage"
   },