Initial commit.

Author: Robert Yawn

.editorconfig

@@ -0,0 +1,13 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.gitignore

@@ -0,0 +1,7 @@
+node_modules
+npm-debug.log
+.env
+.env*
+coverage/
+atlassian-ide-plugin.xml
+.idea

.npmignore

@@ -0,0 +1,7 @@
+*.sw*
+node_modules/
+.DS_Store
+coverage
+test/
+atlassian-ide-plugin.xml
+.idea

LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2014 Pebble Technology
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Makefile

@@ -0,0 +1,15 @@
+
+test:
+	@./node_modules/.bin/mocha -A --harmony-generators test/*Spec.js
+
+test-cov:
+	@NODE_ENV=test node --harmony-generators \
+		node_modules/.bin/istanbul cover \
+		./node_modules/.bin/_mocha \
+		-- -u exports \
+		-A test/*Spec.js
+
+open-cov:
+	open coverage/lcov-report/index.html
+
+.PHONY: test test-cov open-cov

README.md

@@ -0,0 +1,75 @@
+#koa-resourcer-docs
+
+## Introduction
+A simple documentation generator for [koa-resourcer](https://github.com/pebble/koa-resourcer).
+
+App resources that have exposed routes will be parsed and documented.
+
+## Use
+In your app:
+```js
+var koa = require('koa');
+var join = require('path').join;
+var resource = require('koa-resourcer');
+var docs = require('koa-resourcer-docs');
+
+var app = koa();
+resource(app, join(__dirname, 'resources'), docs.addResource);
+app.listen();
+```
+
+In each resource app:
+```js
+var koa = require('koa');
+var Router = require('koa-joi-router');
+
+var router = Router();
+var app = module.exports = koa();
+
+// Expose routes to documentation generator
+app.routes = router.routes;
+
+// Define some routes...
+
+app.use(router.middleware());
+```
+
+## Configuration
+Add a description to the route config:
+```js
+router.get('/', {description: 'Home page'}, function* () {
+  this.body = "Home page under construction since 2009";
+});
+```
+
+Hide a resource by not exposing routes:
+```js
+// Expose routes to documentation generator
+//app.routes = router.routes;
+```
+
+Hide individual routes in a resource app from documentation by adding `hide: true` to route metadata:
+```js
+// Documented route:
+router.get('/', {description: 'Main route'}, function* () {
+  this.body = 'Hello world';
+});
+
+// Hidden route:
+router.get('/secretRoute', {description: 'Nobody here but us chickens.', hide: true}, function* () {
+  this.body = 'This is a hidden world';
+});
+```
+
+## Installation
+```
+npm install koa-resourcer-docs --save
+```
+
+## Sponsored by
+
+[Pebble Technology!](https://getpebble.com)
+
+## LICENSE
+
+[MIT](/LICENSE)

docs.js

@@ -0,0 +1,170 @@
+'use strict';
+
+var fs = require('fs');
+var join = require('path').join;
+var dot = require('dot');
+var koa = require('koa');
+var router = require('koa-joi-router');
+
+var docs = module.exports = koa();
+var r = router();
+
+// holds the routes as they are added by koa-resourcer
+var routes = [];
+
+// expose routes to docs generator
+docs.routes = r.routes;
+
+var templatePath = join(__dirname, 'template.dot');
+var template = loadTemplate(templatePath);
+
+// holds the routes description object
+var objCache = null;
+
+// holds the compiled html routes description string data
+var htmlCache = null;
+
+/**
+ * API documentation in JSON format
+ */
+
+r.get('/json'
+, {
+    description: 'API documentation in JSON format.'
+  }
+, function* () {
+    if (objCache) {
+      this.body = objCache;
+      return;
+    }
+
+    this.body = objCache = { docs: describeRoutes(routes) };
+  }
+);
+
+/**
+ * API documentation in human-readable HTML format
+ */
+
+r.get('/'
+, {
+    description: 'API documentation in human-readable HTML format.'
+  }
+, function* () {
+    if (htmlCache) {
+      this.body = htmlCache;
+      return;
+    }
+
+    if (objCache) {
+      this.body = htmlCache = template(objCache);
+      return;
+    }
+
+    objCache = { docs: describeRoutes(routes) };
+    this.body = htmlCache = template(objCache);
+  }
+);
+
+docs.use(r.middleware());
+
+/**
+ * Handles the route object passed to the resourcer callback
+ * @api public
+ */
+
+docs.addRoute = function addRoute(o) {
+  routes.push(o)
+};
+
+/**
+ * Clear documentation cache
+ * @api public
+ */
+
+docs.clearCache = function clearCache() {
+  htmlCache = null;
+  objCache = null;
+};
+
+/**
+ * Load the documentation template.
+ * @api private
+ */
+
+function loadTemplate(path) {
+  try {
+    return dot.compile(fs.readFileSync(path));
+  } catch (e) {
+    // Ignoring this line for code coverage until custom templates are supported.
+    /* istanbul ignore next */
+    return dot.compile("Failed to load documentation template from path: " + path);
+  }
+}
+
+/**
+ * Produce the routes description object.
+ * @api private
+ */
+
+function describeRoutes(routes) {
+  return routes.filter(function (route) {
+    return isObject(route.resource.routes);
+  }).map(function (route) {
+    return {
+      path: route.path
+    , routes: route.resource.routes.filter(function (route) {
+        return !route.hide;
+      }).map(describeRoute)
+    };
+  });
+}
+
+/**
+ * Produces a human readable description of the route.
+ * @api private
+ */
+
+function describeRoute(route) {
+  var ret = {};
+
+  Object.keys(route).forEach(function(key){
+    if ('handler' == key) return;
+    if ('validate' == key) return;
+    ret[key] = route[key];
+  });
+
+  if (route.validate) {
+    // this is the validation object being used by the routes themselves,
+    // do not change this object.
+    ret.validate = describeObject(route.validate);
+  }
+
+  return ret;
+}
+
+/**
+ * Produces a human readable description of the route validators.
+ * @api private
+ */
+
+function describeObject(o) {
+  if ('function' == typeof o.describe) return o.describe();
+
+  var ret = {};
+  if (!isObject(o)) return o;
+
+  Object.keys(o).forEach(function(key) {
+    ret[key] = describeObject(o[key]);
+  });
+
+  return ret;
+}
+
+/**
+ * @api private
+ */
+
+function isObject(o) {
+  return 'object' == typeof o && null !== o;
+}

package.json

@@ -0,0 +1,45 @@
+{
+  "name": "koa-resourcer-docs",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Simple route documentation for koa-resourcer.",
+  "main": "docs.js",
+  "license": "MIT",
+  "readmeFilename": "README.md",
+  "keywords": [
+    "koa",
+    "koa-joi-router",
+    "koa-resourcer",
+    "resource",
+    "router",
+    "documentation"
+  ],
+  "homepage": "https://github.com/pebble/koa-resourcer-docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pebble/koa-resourcer-docs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pebble/koa-resourcer-docs/issues"
+  },
+  "engines": {
+    "node": ">= 0.11.4"
+  },
+  "dependencies": {
+    "dot": "1.0.2",
+    "koa": "0.10.0",
+    "koa-joi-router": "1.3.0"
+  },
+  "devDependencies": {
+    "koa-resourcer": "1.0.0",
+    "istanbul-harmony": "^0.3.0",
+    "co-mocha": "1.0.1",
+    "co-supertest": "^0.0.7",
+    "mocha": "^1.21.4",
+    "supertest": "^0.13.0"
+  },
+  "scripts": {
+    "test": "make test",
+    "test-cov": "make test-cov"
+  }
+}