spacedocs 0.0.2

data/dox/test/fixtures/c.js

@@ -0,0 +1,266 @@
+
+/*!
+ * Dox
+ * Copyright (c) 2010 TJ Holowaychuk <tj@vision-media.ca>
+ * MIT Licensed
+ */
+
+/**
+ * Module dependencies.
+ */
+
+var markdown = require('github-flavored-markdown').parse;
+
+/**
+ * Library version.
+ */
+
+exports.version = '0.0.5';
+
+/**
+ * Parse comments in the given string of `js`.
+ *
+ * @param {String} js
+ * @return {Array}
+ * @see exports.parseComment
+ * @api public
+ */
+
+exports.parseComments = function(js){
+  var comments = []
+    , comment
+    , buf = ''
+    , ignore
+    , within
+    , code;
+
+  for (var i = 0, len = js.length; i < len; ++i) {
+    // start comment
+    if ('/' == js[i] && '*' == js[i+1]) {
+      // code following previous comment
+      if (buf.trim().length) {
+        comment = comments[comments.length - 1];
+        comment.code = code = buf.trim();
+        comment.ctx = exports.parseCodeContext(code);
+        buf = '';
+      }
+      i += 2;
+      within = true;
+      ignore = '!' == js[i];
+    // end comment
+    } else if ('*' == js[i] && '/' == js[i+1]) {
+      i += 2;
+      buf = buf.replace(/^ *\* ?/gm, '');
+      var comment = exports.parseComment(buf);
+      comment.ignore = ignore;
+      comments.push(comment);
+      within = ignore = false;
+      buf = '';
+    // buffer comment or code
+    } else {
+      buf += js[i];
+    }
+  }
+
+  // trailing code
+  if (buf.trim().length) {
+    comment = comments[comments.length - 1];
+    code = buf.trim();
+    comment.code = code;
+  }
+
+  return comments;
+};
+
+/**
+ * Parse the given comment `str`.
+ *
+ * The comment object returned contains the following:
+ *
+ *  - `tags`  array of tag objects
+ *  - `description` the first line of the comment
+ *  - `body` lines following the description
+ *  - `content` both the description and the body
+ *  - `isPrivate` true when "@api private" is used
+ *
+ * @param {String} str
+ * @return {Object}
+ * @see exports.parseTag
+ * @api public
+ */
+
+exports.parseComment = function(str) {
+  str = str.trim();
+  var comment = { tags: [] }
+    , description = {};
+
+  // parse comment body
+  description.full = str.split('@')[0].replace(/^([\w ]+):/gm, '## $1');
+  description.summary = description.full.split('\n\n')[0];
+  description.body = description.full.split('\n\n').slice(1).join('\n\n');
+  comment.description = description;
+
+  // parse tags
+  if (~str.indexOf('@')) {
+    var tags = '@' + str.split('@').slice(1).join('@');
+    comment.tags = tags.split('\n').map(exports.parseTag);
+    comment.isPrivate = comment.tags.some(function(tag){
+      return 'api' == tag.type && 'private' == tag.visibility;
+    })
+  }
+
+  // markdown
+  description.full = markdown(escape(description.full));
+  description.summary = markdown(escape(description.summary));
+  description.body = markdown(escape(description.body));
+
+  return comment;
+}
+
+/**
+ * Parse tag string "@param {Array} name description" etc.
+ *
+ * @param {String}
+ * @return {Object}
+ * @api public
+ */
+
+exports.parseTag = function(str) {
+  var tag = {} 
+    , parts = str.split(/ +/)
+    , type = tag.type = parts.shift().replace('@', '');
+
+  /* shouldn't fail */
+  switch (type) { // asfasdfasdf /** /////
+    case 'param':
+      tag.types = exports.parseTagTypes(parts.shift());
+      tag.name = parts.shift() || '';
+      tag.description = parts.join(' ');
+      break;
+    case 'return':
+      tag.types = exports.parseTagTypes(parts.shift());
+      tag.description = parts.join(' ');
+      break;
+    case 'see':
+      if (~str.indexOf('http')) {
+        tag.title = parts.length > 1
+          ? parts.shift()
+          : '';
+        tag.url = parts.join(' ');
+      } else {
+        tag.local = parts.join(' ');
+      }
+    case 'api':
+      tag.visibility = parts.shift();
+      break;
+    case 'type':
+      tag.types = exports.parseTagTypes(parts.shift());
+      break;
+  }
+
+  return tag;
+}
+
+/**
+ * Parse tag type string "{Array|Object}" etc.
+ *
+ * @param {String} str
+ * @return {Array}
+ * @api public
+ */
+
+exports.parseTagTypes = function(str) {
+  return str
+    .replace(/[{}]/g, '')
+    .split(/ *[|,\/] */);
+};
+
+/**
+ * Parse the context from the given `str` of js.
+ *
+ * This method attempts to discover the context
+ * for the comment based on it's code. Currently
+ * supports:
+ *
+ *   - function statements
+ *   - function expressions
+ *   - prototype methods
+ *   - prototype properties
+ *   - methods
+ *   - properties
+ *   - declarations
+ *
+ * @param {String} str
+ * @return {Object}
+ * @api public
+ */
+
+exports.parseCodeContext = function(str){
+  var str = str.split('\n')[0];
+
+  // function statement
+  if (/^function (\w+)\(/.exec(str)) {
+    return {
+        type: 'function'
+      , name: RegExp.$1
+    };
+  // function expression
+  } else if (/^var *(\w+) *= *function/.exec(str)) {
+    return {
+        type: 'function'
+      , name: RegExp.$1
+    };
+  // prototype method
+  } else if (/^(\w+)\.prototype\.(\w+) *= *function/.exec(str)) {
+    return {
+        type: 'method'
+      , constructor: RegExp.$1
+      , name: RegExp.$2
+    };
+  // prototype property
+  } else if (/^(\w+)\.prototype\.(\w+) *= *([^\n;]+)/.exec(str)) {
+    return {
+        type: 'property'
+      , constructor: RegExp.$1
+      , name: RegExp.$2
+      , value: RegExp.$3
+    };
+  // method
+  } else if (/^(\w+)\.(\w+) *= *function/.exec(str)) {
+    return {
+        type: 'method'
+      , receiver: RegExp.$1
+      , name: RegExp.$2
+    };
+  // property
+  } else if (/^(\w+)\.(\w+) *= *([^\n;]+)/.exec(str)) {
+    return {
+        type: 'property'
+      , receiver: RegExp.$1
+      , name: RegExp.$2
+      , value: RegExp.$3
+    };
+  // declaration
+  } else if (/^var +(\w+) *= *([^\n;]+)/.exec(str)) {
+    return {
+        type: 'declaration'
+      , name: RegExp.$1
+      , value: RegExp.$2
+    };
+  }
+};
+
+/**
+ * Escape the given `html`.
+ *
+ * @param {String} html
+ * @return {String}
+ * @api private
+ */
+
+function escape(html){
+  return String(html)
+    .replace(/&(?!\w+;)/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

data/dox/test/fixtures/d.js

@@ -0,0 +1,15 @@
+
+/**
+ * Parse tag type string "{Array|Object}" etc.
+ *
+ * @name is arbitrary
+ * @param {String} str
+ * @return {Array}
+ * @api public
+ */
+
+exports.parseTagTypes = function(str) {
+  return str
+    .replace(/[{}]/g, '')
+    .split(/ *[|,\/] */);
+};

data/dox/test/fixtures/titles.js

@@ -0,0 +1,14 @@
+
+/**
+ * Description.
+ * 
+ * Some examples:
+ * 
+ *  foo
+ * 
+ * Some longer thing
+ * for example:
+ * 
+ *  bar
+ * 
+ */

data/lib/assets/stylesheets/spacedocs/docs.css.sass

@@ -0,0 +1,155 @@
+@import compass/css3
+
+$width: 600px
+
+html
+  color: #222
+  height: 100%
+
+body
+  +background-image(linear-gradient(135deg, rgba(0, 0, 0, 0.05) 25%, transparent 25%, transparent 50%, rgba(0, 0, 0, 0.05) 50%, rgba(0, 0, 0, 0.05) 75%, transparent 75%, transparent))
+  -webkit-background-size: 4px 4px
+
+  font-family: 'Lucida Grande', Arial, sans-serif
+  font-size: 13px
+  height: 100%
+  margin: 0
+
+.method_list
+  +border-radius(5px)
+  +box-shadow(rgba(0,0,0,0.15) 0 0 15px)
+
+  position: fixed
+  top: 20px
+  right: 20px
+  background-color: white
+  border: 1px solid rgba(0, 0, 0, 0.3)
+  max-width: 210px
+  text-align: center
+  margin: 0
+  padding: 0.25em 0.5em
+
+  h3
+    text-align: center
+    margin: 0
+    margin-top: 0.5em
+
+  a
+    color: #222
+    display: inline-block
+    padding: 0.4em 0.5em
+    text-decoration: none
+
+nav
+  +background-image(linear-gradient(45deg, rgba(0, 0, 0, 0.05) 25%, transparent 25%, transparent 50%, rgba(0, 0, 0, 0.05) 50%, rgba(0, 0, 0, 0.05) 75%, transparent 75%, transparent))
+  +box-shadow(rgba(0, 0, 0, 0.15) -1px 0 4px inset)
+  -webkit-background-size: 12px 12px
+  display: inline-block
+  width: 130px
+  height: 100%
+  border-right: 1px solid rgba(0, 0, 0, 0.2)
+  background-color: rgba(0, 0, 0, 0.15)
+  padding: 0.5em 0
+  position: fixed
+  left: 0
+  overflow: auto
+  top: 0
+
+  a
+    +box-sizing(border-box)
+
+    border: 1px solid transparent
+    color: #222
+    display: block
+    text-decoration: none
+    padding: 0.5em 0 0.5em 1em
+
+    &.active
+      +border-left-radius(5px)
+      +box-shadow(rgba(0, 0, 0, 0.2) 0 0 4px)
+
+      background-image: -webkit-linear-gradient(135deg, rgba(0, 0, 0, 0.05) 25%, transparent 25%, transparent 50%, rgba(0, 0, 0, 0.05) 50%, rgba(0, 0, 0, 0.05) 75%, transparent 75%, transparent)
+      background-color: white
+      background-size: 4px 4px
+      padding: 0.5em 0 0.5em 0.5em
+      margin-left: 0.5em
+      border-right: 1px white
+      border: 1px solid rgba(0, 0, 0, 0.3)
+      border-right: 1px solid rgba(0, 0, 0, 0.15)
+
+.documentation
+  display: inline-block
+  max-width: $width
+  padding-left: 145px
+  vertical-align: top
+
+  a, a:active, a:visited, a:hover
+    color: #307EB6
+
+  h1, h2, h3, h4, h5
+    display: inline-block
+    margin: 0
+
+  h1
+    font-size: 1.5em
+
+  p
+    margin: 0.5em 0
+
+  ul
+    margin: 0
+    padding-left: 1em
+    list-style: none
+
+    li
+      padding-top: 0.5em
+
+  .returns
+    p
+      margin-left: 1em
+
+  section
+    margin-bottom: 0.75em
+
+  .source pre
+    display: none
+
+  .toggle_source
+    cursor: pointer
+
+  pre
+    margin: 0.5em 0
+
+  .param_name
+    font-style: italic
+
+  .description
+    margin-left: 1em
+
+    p code
+      +border-radius(4px)
+      +box-shadow(rgba(0, 0, 0, 0.15) 0 0 4px inset)
+
+      background-color: #EEE
+      border: 1px solid rgba(0, 0, 0, 0.2)
+      padding: 0 0.3em
+
+  .description, .source
+    pre
+      +border-radius(4px)
+      +box-shadow(rgba(0, 0, 0, 0.15) 0 0 4px inset)
+      +box-sizing(border-box)
+
+      border: 1px solid rgba(0, 0, 0, 0.2)
+      background-color: #EEE
+      max-width: $width
+      padding: 0.5em 1em
+
+  hr
+    margin-left: 1px
+    margin-top: 1em
+    margin-bottom: 1em
+    max-width: $width
+
+    &:last-child
+      display: none

data/lib/spacedocs/engine.rb

@@ -0,0 +1,6 @@
+module Spacedocs
+  class Engine < Rails::Engine
+    # tells rails to add the project's app/assets, lib/assets,
+    # and vendor/assets to the asset load path.
+  end
+end

data/lib/spacedocs/version.rb

@@ -0,0 +1,3 @@
+module Spacedocs
+  VERSION = "0.0.2"
+end

data/lib/spacedocs.rb

@@ -0,0 +1,215 @@
+require 'tilt'
+require 'haml'
+require 'json'
+require 'fileutils'
+
+module Spacedocs
+  class << self
+    def doc(project_dir, file)
+      tilt_path = File.dirname(__FILE__)
+
+      #TODO Dangerous
+      json = %x[dox < "#{File.join project_dir, file}"]
+
+      doc_json = JSON.parse json
+
+      processed_data = process_data doc_json
+
+      template = Tilt.new(File.join tilt_path, "../source/class.html.haml")
+      index_template = Tilt.new(File.join tilt_path, "../source/index.html.haml")
+
+      files = {}
+
+      class_data = processed_data[:docs_data]
+
+      class_data.each_key do |namespace|
+        files[namespace] = true
+      end
+
+      docs_dir = File.join(project_dir, 'docs')
+
+      FileUtils.rm_rf docs_dir
+      FileUtils.mkdir_p docs_dir
+
+      if __FILE__ == $0
+        File.open("source/index.html", 'w') do |f|
+          f.write(index_template.render self, { class_names: files.keys, dev: true })
+        end
+
+        files.each_key do |file_name|
+          methods = class_data[file_name]['methods']
+
+          File.open("source/#{file_name}.html", 'w') do |f|
+            f.write(template.render self, {
+              class_name: file_name,
+              method_list: methods.keys,
+              methods: methods,
+              class_names: files.keys,
+              class_summary: class_data[file_name]['summary'],
+              dev: true
+            })
+          end
+        end
+      else
+        File.open(File.join(project_dir, "docs/index.html"), 'w') do |f|
+          f.write(index_template.render self, { class_names: files.keys })
+        end
+
+        files.each_key do |file_name|
+          methods = class_data[file_name]['methods']
+
+          File.open(File.join(project_dir, "docs/#{file_name}.html"), 'w') do |f|
+            f.write(template.render self, {
+              class_name: file_name,
+              method_list: methods.keys,
+              methods: methods,
+              class_names: files.keys,
+              class_summary: class_data[file_name]['summary'],
+              dev: false
+            })
+          end
+        end
+      end
+    end
+
+    private
+    def tags_named(name, tags)
+      tags.map do |tag|
+        tag['string'] if tag['type'] == name
+      end.compact
+    end
+
+    def method_of_data(tags)
+      tags_named('methodOf', tags)
+    end
+
+    def name_data(tags)
+      tags_named('name', tags)
+    end
+
+    def format_class_name(name)
+      if name.end_with?('#')
+        name[0...-1]
+      else
+        name
+      end
+    end
+
+    def params_data(tags)
+      tags.each_with_object({}) do |tag, hash|
+        if tag['type'] == 'param'
+          hash["#{tag['name'].gsub(/[\[\]]/, '')}"] = {
+            "type" => tag['types'].join(', '),
+            "description" => tag['description'],
+            "optional" => tag['name'].start_with?('[')
+          }
+        end
+      end
+    end
+
+    def returns_data(tags)
+      tags.map do |tag|
+        if tag['type'] == 'returns'
+          description = tag['string'].split ' '
+
+          type = description.shift.gsub(/[{}]/, '')
+          remaining = description.join ' '
+
+          { "type" => type, "description" => remaining }
+        end
+      end.compact
+    end
+
+    def see_data(tags)
+      tags_named('see', tags)
+    end
+
+    def class_name_data(tags)
+      class_names = []
+
+      tags.each do |tag|
+        class_names << format_class_name(tag['string']) if tag['type'] == 'methodOf'
+
+        if ['constructor', 'namespace'].include? tag['type']
+          tags.each do |tag|
+            class_names << tag['string'] if tag['type'] == 'name'
+          end
+        end
+      end
+
+      class_names.first
+    end
+
+    def process_data(json)
+      class_names = []
+      tags_list = []
+      docs_data = {}
+      module_map = {}
+      class_summaries = {}
+
+      json.each do |item|
+        tags = item['tags']
+
+        tags.each do |tag|
+          if ['constructor', 'namespace'].include? tag['type']
+            class_summaries[class_name_data(tags)] ||= {}
+            class_summaries[class_name_data(tags)]['description'] ||= {}
+
+            class_summaries[class_name_data(tags)]['description']['summary'] = item['description']['summary'] || ""
+            class_summaries[class_name_data(tags)]['description']['body'] = item['description']['body'] || ""
+          end
+        end
+
+        tags_list << tags
+
+        name = name_data(tags).first
+        returns = returns_data(tags).first || {}
+        see = see_data(tags).first || ""
+        method_of = method_of_data(tags).first
+        params = params_data(tags)
+
+        class_names << class_name_data(tags)
+
+        if name && method_of
+          if method_of.end_with?('#')
+            name = "##{name}"
+            method_of = method_of[0...-1]
+          else
+            name = ".#{name}"
+          end
+
+          module_map[method_of] ||= {}
+          module_map[method_of][name] = {
+            "summary" => item['description']['summary'],
+            "code_sample" => item['description']['body'],
+            "source" => item['code'],
+            "parameters" => params,
+            "returns" => returns,
+            "see" => see
+          }
+        end
+      end
+
+      class_names = class_names.compact.flatten.uniq.sort
+
+      class_names.each do |source_class|
+        method_data = module_map[source_class] || {}
+
+        docs_data[source_class] = {
+          'summary' => class_summaries[source_class],
+          'methods' => method_data
+        }
+      end
+
+      # File.open("source/sanity.json", 'w') do |f|
+      #   f.write(JSON.pretty_generate(docs_data))
+      # end
+
+      return { docs_data: docs_data, class_names: class_names }
+    end
+  end
+end
+
+if __FILE__ == $0
+  Spacedocs.doc 'projects/6', 'game.js'
+end