From 7e056e527898aac96ec4257d2fd35df24e7cec21 Mon Sep 17 00:00:00 2001 From: Andre Casey Date: Sat, 28 Sep 2013 11:43:01 -0700 Subject: [PATCH 1/3] Removed Docker from Gruntfile. Changed Docs readme filename. --- docs-home.md => DOCS-README.md | 0 Gruntfile.js | 24 +----------------------- 2 files changed, 1 insertion(+), 23 deletions(-) rename docs-home.md => DOCS-README.md (100%) diff --git a/docs-home.md b/DOCS-README.md similarity index 100% rename from docs-home.md rename to DOCS-README.md diff --git a/Gruntfile.js b/Gruntfile.js index 6b395980d2..6c0d976cb7 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -4,27 +4,6 @@ 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' @@ -185,7 +164,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', 'docker']); + grunt.registerTask('build:dev', ['clean:build', 'stylus', 'cssmin', 'copy:build', 'hashres']); grunt.registerTask('run:dev', [ 'build:dev', 'concurrent' ]); @@ -200,6 +179,5 @@ module.exports = function(grunt) { grunt.loadNpmTasks('grunt-contrib-watch'); grunt.loadNpmTasks('grunt-hashres'); grunt.loadNpmTasks('grunt-karma'); - grunt.loadNpmTasks('grunt-docker'); }; From a1c4db8727069ed327a932a0f700a31403d75544 Mon Sep 17 00:00:00 2001 From: Andre Casey Date: Sat, 28 Sep 2013 14:59:34 -0700 Subject: [PATCH 2/3] Updated DOCS-README.md for Docker --- DOCS-README.md | 89 +++++++++++++++++++++++++------------------------- 1 file changed, 44 insertions(+), 45 deletions(-) diff --git a/DOCS-README.md b/DOCS-README.md index 06e7c61a9e..e21c420b16 100644 --- a/DOCS-README.md +++ b/DOCS-README.md @@ -4,75 +4,74 @@ Generated documentation for all of HabitRPG's source files will be kept in the f ## 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 +You're looking at it! -Example using MAMP: -```` -http://localhost:8888/habitrpg/documentation/docs/ -```` +Unless you are viewing this file directly from GitHub, you should see a list of files and folders to the left of this readme. -Then click on the file you want to view. Done. +If you are working locally, you can goto `localhost:3000/docs/` and view the Docs. + +All documentation is generated from comments in the code, into HTML files in the `public/docs/` folder. After you have cloned the HabitRPG repo locally, and done all the `npm install` goodness, the Docs should generate automagickly when you run `grunt run:dev` ## 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 - }, .... +/* +User.js +======= + +Defines the user data model (schema) for use via the API. +*/ + +// Dependencies +// ------------ +var mongoose = require("mongoose"); +var Schema = mongoose.Schema; +var helpers = require('habitrpg-shared/script/helpers'); +var _ = require('lodash');.... ```` -All comments need to be on their own line. Thus this won't work: +As you can see, you can use both multiline style comments `/* fancy stuff */` and inline comments `// Ooooh my`. +The exception being end of line comments `text: String, // example: Wolf ` -This will: - -```` -// example: Wolf -text: String, -```` +The above will not be on the "pretty print" side of the Docs, but will stay in the code. An example use case for end of line comments would be for FIXME notes. 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. +**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. + +### jsDoc Syntax + +Yes, the generator also supports jsDoc-style comments such as +```` +@param {Array} files Array of file paths relative to the `inDir` to generate documentation for. +```` + +**Important Note:** If you use the `@param` syntax, you must use multiline comment blocks (ie `/* stuff */`), otherwise they won't be parsed like parameters. + +This may or may not be useful for HabitRPG. Example use cases: +- Documenting the API +- Javascript Models ## Okay, I added great comments. Now what? -Now the source files need to be run through [Docco](http://jashkenas.github.io/docco/). +If you're running locally, just re-run `grunt run:dev`. Any changed docs will be automagickly updated. -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. +Once you're satisfied with the output, push your changes to your fork of HabitRPG and issue a Pull Request on the `docs-project` branch. -### Requirements +It's that easy! -Install Docco: `sudo npm install -g docco` +## Tech Info -### Generating +The generator we are using is [Docker](https://github.com/jbt/docker), which is a fork of [Docco](http://jashkenas.github.io/docco/). Docker supports the same wide-range of filetypes, including being able to generate documentation for a whole project, including an index. -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. +We also use the [Grunt-Docker](https://github.com/Prevole/grunt-docker) node module for automatic processing. ## 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 +- Customize CSS with HabitRPG specific Styling +- Explore possibilities of importing Wiki content +- Specify style guide for consistency of comments \ No newline at end of file From 730c82ccaf6d8d4d847999765d99bee75d7a5f07 Mon Sep 17 00:00:00 2001 From: Andre Casey Date: Mon, 30 Sep 2013 19:11:14 -0700 Subject: [PATCH 3/3] Removes devDependecies for docker from Package.json. --- package.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/package.json b/package.json index 6b3c81c892..1939c440e2 100644 --- a/package.json +++ b/package.json @@ -72,8 +72,6 @@ "karma": "~0.10.2", "karma-ng-html2js-preprocessor": "~0.1.0", "mocha": "~1.12.1", - "karma-mocha": "~0.1.0", - "docker": "~0.2.8", - "grunt-docker": "0.0.5" + "karma-mocha": "~0.1.0" } }