From 92485a938e30c4ba9f8d273d3eba6a5e423eaee0 Mon Sep 17 00:00:00 2001
From: Andre Casey <me@andrecasey.com>
Date: Tue, 24 Sep 2013 00:53:46 -0700
Subject: [PATCH] Documentation configuration for Docker

Includes:
- Gruntfile config
- read me for docs (docs-home.md. maps to --> docs-home.md.html)
- updated package.json for docker dep
- updated .gitignore to not include generated files
---
 .gitignore   |  3 +-
 Gruntfile.js | 24 +++++++++++++++-
 docs-home.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 package.json |  4 ++-
 4 files changed, 106 insertions(+), 3 deletions(-)
 create mode 100644 docs-home.md

diff --git a/.gitignore b/.gitignore
index c0f0054b81..a7d8e7d2e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,4 +12,5 @@ build
 src/*/*.map
 src/*/*/*.map
 test/*.js
-test/*.map
\ No newline at end of file
+test/*.map
+public/docs
diff --git a/Gruntfile.js b/Gruntfile.js
index 6c0d976cb7..6b395980d2 100644
--- a/Gruntfile.js
+++ b/Gruntfile.js
@@ -4,6 +4,27 @@ module.exports = function(grunt) {
   // Project configuration.
   grunt.initConfig({
 
+    // Documentation Generator
+    // See -> https://github.com/jbt/docker & https://npmjs.org/package/grunt-docker
+    docker: {
+      app: {
+        expand: true,
+        src: ['src/*', 'views/*.jade', 'views/**/*.jade', 'public/css/*.styl', 'docs-home.md'],
+        dest: './public/docs',
+        options: {
+          onlyUpdated: true,
+          colourScheme: 'manni',
+          ignoreHidden: false,
+          sidebarState: true,
+          exclude: true,
+          lineNums: false,
+          js: [],
+          css: [],
+          extras: []
+        }
+      }
+    },
+
     karma: {
       unit: {
         configFile: 'karma.conf.js'
@@ -164,7 +185,7 @@ module.exports = function(grunt) {
 
   // Register tasks.
   grunt.registerTask('build:prod', ['clean:build', 'uglify', 'stylus', 'cssmin', 'copy:build', 'hashres']);
-  grunt.registerTask('build:dev', ['clean:build', 'stylus', 'cssmin', 'copy:build', 'hashres']);
+  grunt.registerTask('build:dev', ['clean:build', 'stylus', 'cssmin', 'copy:build', 'hashres', 'docker']);
 
   grunt.registerTask('run:dev', [ 'build:dev', 'concurrent' ]);
 
@@ -179,5 +200,6 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-contrib-watch');
   grunt.loadNpmTasks('grunt-hashres');
   grunt.loadNpmTasks('grunt-karma');
+  grunt.loadNpmTasks('grunt-docker');
 
 };
diff --git a/docs-home.md b/docs-home.md
new file mode 100644
index 0000000000..06e7c61a9e
--- /dev/null
+++ b/docs-home.md
@@ -0,0 +1,78 @@
+# HabitRPG Docs Project
+
+Generated documentation for all of HabitRPG's source files will be kept in the folder and subfolders. If you would like to use the existing documentation, or contribute to the documentation efforts, read on.
+
+## Viewing Docs
+
+All documentation is generated into HTML files in the `docs/` folder. After you have cloned the HabitRPG repo locally, make sure it is readable by your webserver and navigate to documentation directory
+
+Example using MAMP:
+````
+http://localhost:8888/habitrpg/documentation/docs/
+````
+
+Then click on the file you want to view. Done.
+
+## What I do now?
+
+Well if you know Markdown, simply add detailed comments in the code using Markdown syntax. 
+
+````
+// ### Mongoose Update Object
+  // We want to know *every* time an object updates. Mongoose uses __v to designate when an object contains arrays which
+  // have been updated (http://goo.gl/gQLz41), but we want *every* update
+  _v: {
+    type: Number,
+    'default': 0
+  }, ....
+````
+
+All comments need to be on their own line. Thus this won't work:
+
+`text: String, // example: Wolf `
+
+This will:
+
+````
+// example: Wolf
+text: String,
+````
+
+Add anything that would be helpful to a developer regarding how to use the functions, variables, and objects associated with HabitRPG.
+
+**All documentation should be committed as pull request to the `docs project` branch of HabitRPG.** Since we are adding comments directly to the code, I don't want to be editing files used for beta or master. We can merge in the docs after we're sure we didn't break anything. 
+
+## Okay, I added great comments. Now what?
+
+Now the source files need to be run through [Docco](http://jashkenas.github.io/docco/).
+
+This is the Generator we are using for now. It's pretty basic, but it gets the job done. Most of the documentation generators out there use Markdown, so it wouldn't be hard to switch to another one, should we choose to down the road.
+
+### Requirements
+
+Install Docco: `sudo npm install -g docco`
+
+### Generating
+
+Docco needs to be ran on each source file. For now we are focusing on .js, although we may do the same thing with .css/scss in the future. 
+
+Currently, Docco needs to be ran manually. [As of Sept 19th, 2013] There are only 4 commands that need to be run to generate documentation for every source file.
+
+All commands need to be ran from the `documentation/` directory. 
+````
+docco -c docco.css ../src/*.js
+docco -c docco.css ../src/models/*.js
+docco -c docco.css ../src/controllers/*.js
+docco -c docco.css ../src/routes/*.js
+````
+This will place the generated html files into the `docs/` directory.
+
+Of course, you only need to run docco on the files you have changed.
+
+**Make sure to include the `-c docco.css` bit!** I tweaked the default css a bit so that the lines and heading match up better. Without this docco will overwrite it with it's own. 
+
+## Road Map
+
+- Generate documentation automagickly using grunt task
+- Change default css, so `-c docco.css` attribute isn't needed
+- Add support for CSS documentation
\ No newline at end of file
diff --git a/package.json b/package.json
index 1939c440e2..6b3c81c892 100644
--- a/package.json
+++ b/package.json
@@ -72,6 +72,8 @@
     "karma": "~0.10.2",
     "karma-ng-html2js-preprocessor": "~0.1.0",
     "mocha": "~1.12.1",
-    "karma-mocha": "~0.1.0"
+    "karma-mocha": "~0.1.0",
+    "docker": "~0.2.8",
+    "grunt-docker": "0.0.5"
   }
 }