Add a Jekyll-based documentation site

There's a wealth of content in the readme, and an opportunity to write
additional user guides. However, the documentation site currently features
only the generated API docs, and ever since #145 the generated docs are
not as robust as they were before. To better highlight the documentation
contained within the REAMDE, in this PR we

- Add grunt task to zip built browser bundles (for #196)
- Implement a task to generate jekyll-ready pages from README
- Generate a documentation index with deep links to the subheds of
  content extracted from the README file
- Update CONTRIBUTING and README files to generate better output
- Add a script to print out tasks necessary to release docs branch
- Add a docs site favicon and add IE fallback favicon link
- Add a convenience package script to run jekyll in dev mode
- Add a grunt task to clean leftover files after docs release
- Reorganize Grunt tasks into modules within `build/grunt/`
- Lint build and bin directories, with support for es2015 syntax
- Support arbitrary host when running jekyll in local dev environment

There's a lot that could be done to improve the generated documentation, but as-is this closes #196

Closes #205 (this is a squashed PR)

.gitignore

@@ -31,6 +31,12 @@ test.js
 docs/
 index.html
 
+# Dynamic content within Jekyll documentation site
+documentation/*.md
+documentation/*.zip
+documentation/index.html
+*.ignore
+
 # Webstorm config folder
 .idea
 

CONTRIBUTING.md

@@ -1,5 +1,4 @@
-Contributing
-============
+# Contributing
 
 WordPress is a community effort, as is the WP-API; this client library should be, too. We welcome contributions, however big or small!
 
@@ -63,10 +62,14 @@ Commit messages should follow the standard laid out in the git manual; that is,
 
     Further paragraphs come after blank lines.
 
-     - Bullet points are okay, too
+    - Bullet points are okay, too
 
-     - Typically a hyphen or asterisk is used for the bullet, preceded by a
-       single space, with blank lines in between, but conventions vary here
+    - Typically a hyphen or asterisk is used for the bullet, preceded by a
+      single space, with blank lines in between, but conventions vary
+
+    If the commit relates to an issue -- and most commits should -- you
+    can reference the issue with "For #X" or "Fixes #X", where X is the
+    number of the github issue.
 
 #### Commit & Pull Request Process
 
@@ -76,7 +79,7 @@ We rebase feature branches onto master when merging in order to maintain a linea
 
 ## Code Syntax & Style
 
-We use [JSCS](https://www.npmjs.org/package/jscs) to enforce a basic set of code style guidelines, and [JSHint](http://jshint.com/) to guard against syntax errors. To run them both execute `npm run lint` (or `grunt jscs jshint`, if you have the Grunt command-line tool installed).
+We use [JSCS](https://www.npmjs.org/package/jscs) to enforce a basic set of code style guidelines, and [JSHint](http://jshint.com/) to guard against syntax errors. To run them both execute `npm run lint`; they will also be run every time you execute `npm test`.
 
 JSCS is a useful tool for enforcing a code style, but isn't flexible enough to cover all guidelines. Note our standard for spacing within function parentheses, which is not enforced mechanically but will be evaluated manually when reviewing pull requests:
 ```javascript

Gruntfile.js

@@ -1,31 +1,22 @@
+/**
+ * The Gruntfile in this project is not responsible for the code build or
+ * linting, and instead handles all tasks related to documentation generation
+ * and output.
+ */
 'use strict';
 
 module.exports = function( grunt ) {
-
 	grunt.initConfig({
-
-		pkg: grunt.file.readJSON( 'package.json' ),
-
-		yuidoc: {
-			compile: {
-				name: '<%= pkg.name %>',
-				description: '<%= pkg.description %>',
-				version: '<%= pkg.version %>',
-				url: '<%= pkg.homepage %>',
-				options: {
-					ignorePaths: [ 'node_modules', 'tests' ],
-					paths: '.',
-					themedir: './docs-theme',
-					// theme: 'simple',
-					outdir: 'docs/',
-					tabtospace: 2
-				}
-			}
-		}
-
+		pkg: grunt.file.readJSON( 'package.json' )
 	});
 
-	grunt.loadNpmTasks( 'grunt-contrib-yuidoc' );
+	// Individual tasks are defined within build/grunt
+	grunt.loadTasks( 'build/grunt' );
 
-	grunt.registerTask( 'docs', [ 'yuidoc' ] );
+	grunt.registerTask( 'docs', [
+		'clean',
+		'generate_readme_docs',
+		'zip',
+		'yuidoc'
+	]);
 };

bin/.jshintrc

@@ -0,0 +1,14 @@
+{
+  "boss": true,
+  "curly": true,
+  "eqeqeq": true,
+  "eqnull": true,
+  "expr": true,
+  "noarg": true,
+  "strict": "global",
+  "undef": true,
+  "unused": true,
+
+  "node": true,
+  "esversion": 6
+}

bin/jekyll

@@ -0,0 +1,40 @@
+#!/bin/sh
+':' //; exec "$(command -v nodejs || command -v node)" "$0" "$@"
+// ^^^ Lovely polyglot script to permit usage via node _or_ via bash: see
+// http://unix.stackexchange.com/questions/65235/universal-node-js-shebang
+/**
+ * This script will start the Jekyll server in the context of the docs
+ * directory. It is only for use in local development, and sets the --baseurl
+ * option to override the production-only baseurl in _config.yml.
+ */
+'use strict';
+
+const path = require( 'path' );
+const spawn = require( 'child_process' ).spawn;
+const argv = require( 'minimist' )( process.argv.slice( 2 ) );
+
+// Execute within the context of the docs directory
+const docsDir = path.resolve( __dirname, '../documentation' );
+
+if ( argv.install || argv.i ) {
+  // Install the ruby bundle needed to run jekyll
+  const server = spawn( 'bundle', [ 'install' ], {
+    cwd: docsDir,
+    stdio: 'inherit'
+  });
+
+  server.on( 'error', err => console.error( err ) );
+} else {
+  // Start the server in local dev mode
+  const bundleOptions = [ 'exec', 'jekyll', 'serve', '--baseurl', '' ];
+  if ( argv.host ) {
+    bundleOptions.push( '--host', argv.host );
+  }
+
+  const server = spawn( 'bundle', bundleOptions, {
+    cwd: docsDir,
+    stdio: 'inherit'
+  });
+
+  server.on( 'error', err => console.error( err ) );
+}

build/.jshintrc

@@ -0,0 +1,14 @@
+{
+  "boss": true,
+  "curly": true,
+  "eqeqeq": true,
+  "eqnull": true,
+  "expr": true,
+  "noarg": true,
+  "strict": "global",
+  "undef": true,
+  "unused": "vars",
+
+  "node": true,
+  "esversion": 6
+}

build/grunt/clean.js

@@ -0,0 +1,20 @@
+'use strict';
+
+module.exports = function( grunt ) {
+	grunt.config.set( 'clean', {
+		generated_api_docs: [ 'documentation/api-reference' ],
+		generated_pages: [ 'documentation/*.md' ],
+		generated_index: [ 'documentation/index.html' ],
+		generated_zip: [ 'documentation/*.zip' ],
+		leftover_pages_from_docs_branch: [
+			'./Gemfile.lock',
+			'./_pages/',
+			'./_site/',
+			'./api-reference/',
+			'./css/',
+			'./index.html.combyne'
+		]
+	});
+
+	grunt.loadNpmTasks( 'grunt-contrib-clean' );
+};

build/grunt/generate-docs.js

@@ -0,0 +1,19 @@
+'use strict';
+
+module.exports = function( grunt ) {
+	grunt.registerTask( 'generate_readme_docs', [
+		'Parse the contents of README.md out into individual markdown pages that',
+		'can be rendered with Jekyll.'
+	].join( ' ' ), function() {
+		// Force task into async mode and grab a handle to the "done" function.
+		var done = this.async();
+
+		grunt.log.writeln( 'Extracting page content from README.md...' );
+
+		// Kick off generation
+		require( '../scripts/generate-docs-markdown' ).then(function() {
+			grunt.log.writeln( 'Pages generated successfully' );
+			done();
+		});
+	});
+};

build/grunt/yuidoc.js

@@ -0,0 +1,23 @@
+'use strict';
+
+module.exports = function( grunt ) {
+	grunt.config.set( 'yuidoc', {
+		compile: {
+			name: '<%= pkg.name %>',
+			description: '<%= pkg.description %>',
+			version: '<%= pkg.version %>',
+			url: '<%= pkg.homepage %>',
+			options: {
+				ignorePaths: [ 'node_modules', 'tests', 'browser' ],
+				exclude: 'browser',
+				paths: '.',
+				themedir: './docs-theme',
+				// theme: 'simple',
+				outdir: 'documentation/api-reference',
+				tabtospace: 2
+			}
+		}
+	});
+
+	grunt.loadNpmTasks( 'grunt-contrib-yuidoc' );
+};

build/grunt/zip.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = function( grunt ) {
+	grunt.config.set( 'zip', {
+			bundle: {
+				cwd: 'browser',
+				src: [ 'browser/**/*', 'LICENSE' ],
+				dest: 'documentation/wpapi.zip'
+			}
+		});
+
+	grunt.loadNpmTasks( 'grunt-zip' );
+};