dress_code 1.0.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Instructure, Inc.
+
+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.
+

data/README.md

@@ -0,0 +1,89 @@
+Dress Code
+==========
+
+You haven't shown up to the office in your underwear, neither should your UI.
+
+## About
+
+Dress Code extracts certain comment blocks from your stylesheets and creates a styleguide with them.
+
+Its really flexible, you can:
+
+- Include your own CSS
+- Include your own JS
+- Render the styleguide with your own template
+
+## Installation
+
+`gem install dress_code`
+
+Dress code requires the python library "pygments" for syntax highlighting.
+
+`sudo easy_install pygments`
+
+## Usage
+
+Dress Code is generally used as a command line tool that takes a yaml config file. It will search your files and extract documentation that matches a regular expresssion.
+
+Usage:
+
+    dress_code [config_path]
+
+Example:
+
+    dress_code config/styleguide.yml
+
+Example config yaml file:
+
+```yaml
+# required - the file to generate
+out_file: styleguide/index.html
+
+# required - the files to extract docs from
+glob: stylesheets/**/*.css
+
+# optional - components can display where they are defined, this will be
+# stripped from that definition
+base_dir: stylesheets
+
+# optional - mustache template rendered for the `out_file`
+template: styleguide/index.mustache
+
+# optional - CSS files to load in the template
+css:
+  - public/stylesheets/framework.css
+  - public/stylesheets/app.css
+
+# optional - Inline DressCode CSS styles, defaults to true
+dress_code_css: false
+
+# optional - JavaScript files to load in the template
+js:
+  - public/js/behaviors.js
+
+# optional - Inline DressCode JS, defaults to true
+dress_code_js: false
+```
+
+## Documentation Syntax
+
+Comments like the following will be extracted from your stylesheets:
+
+    /*
+    @styleguide Buttons
+
+    Buttons are amazing.
+
+    ```html
+    <button class="btn">Button</button>
+    ```
+    */
+
+The content of your comment block is parsed as yaml. HTML code fences will be syntax highlighted and rendered in your styleguide.
+
+Feel free to extend `DressCode::Extractor` to match your own style of comments.
+
+## API
+
+You can require any of the classes in lib to extend Dress Code for your particular needs. Check out `bin/dress_code` to see how to use them.
+

data/bin/dress_code

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+
+require 'colored'
+require 'yaml'
+require_relative '../lib/dress_code'
+
+help = "
+
+  Usage:
+
+    dress_code [config_path]
+
+  Example:
+
+    dress_code config/styleguide.yml
+
+"
+
+config_help = "
+  Example config yaml file:
+
+    #{'# required - the file to generate'.yellow}
+    out_file: styleguide/index.html
+
+    #{'# required - the files to extract docs from'.yellow}
+    glob: stylesheets/**/*.css
+
+    #{'# optional - components can display where they are defined, this will be'.yellow}
+    #{'# stripped from that definition'.yellow}
+    base_dir: stylesheets
+
+    #{'# optional - mustache template rendered for the `out_file`'.yellow}
+    template: styleguide/index.mustache
+
+    #{'# optional - CSS files to load in the template'.yellow}
+    css:
+      - public/stylesheets/framework.css
+      - public/stylesheets/app.css
+
+
+    #{'# optional - Inline DressCode CSS styles, defaults to true'.yellow}
+    dress_code_css: false
+
+    #{'# optional - JavaScript files to load in the template'.yellow}
+    js:
+      - public/js/behaviors.js
+
+    #{'# optional - Inline DressCode JS, defaults to true'.yellow}
+    dress_code_js: false
+
+"
+
+config_path = ARGV[0]
+
+if ['--help', '-h'].include?(ARGV[0])
+  puts help + config_help
+  exit
+end
+
+if !config_path
+  puts help
+  exit
+end
+
+begin
+  config = YAML::load_file(config_path)
+rescue
+  puts help + "Error: Could not find config file at '#{config_path}'.".red
+  exit
+end
+
+if !config['out_file']
+  puts config_help + "Error: I need an `out_file` in your config, view the sample above.".red
+  exit
+end
+
+if !config['glob']
+  puts config_help + "Error: I need a `glob` in your config, view the sample above.".red
+  exit
+end
+
+extractor = DressCode::Extractor.new({
+  :files => Dir.glob(config['glob']),
+  :base_dir => config['base_dir']
+})
+generator = DressCode::Generator.new({
+  :out_file => config['out_file'],
+  :docs => extractor.docs,
+  :css => config['css'],
+  :js => config['js'],
+  :dress_code_css => config['dress_code_css'],
+  :dress_code_js => config['dress_code_js']
+})
+generator.generate()
+

data/lib/dress_code.rb

@@ -0,0 +1,3 @@
+module DressCode; end
+Dir[File.dirname(__FILE__) + '/dress_code/**/*.rb'].each {|file| require file }
+

data/lib/dress_code/document.rb

@@ -0,0 +1,27 @@
+require_relative '../dress_code'
+require_relative 'renderer'
+
+class DressCode::Document
+
+  MD = Redcarpet::Markdown.new(DressCode::Renderer.new, {
+    fenced_code_blocks: true,
+    strikethrough: true,
+    superscript: true
+  })
+
+  attr_accessor :path, :relative_path, :prose, :component
+
+  def initialize(attributes)
+    @attributes = attributes
+    @path = @attributes[:path]
+    @relative_path = @attributes[:relative_path]
+    @prose = @attributes[:prose]
+    @component = @attributes[:component]
+  end
+
+  def to_html
+    MD.render(@prose)
+  end
+
+end
+

data/lib/dress_code/extractor.rb

@@ -0,0 +1,46 @@
+require_relative '../dress_code'
+require_relative 'document'
+require 'debugger'
+
+class DressCode::Extractor
+
+  attr_accessor :files
+
+  def initialize(opts)
+    @files = opts[:files]
+    @base_dir = opts[:base_dir]
+    @matcher = %r{/*\s+@styleguide\s+([^\n]+)(.+?)\*/}m
+  end
+
+  def extract
+    parse_files.sort_by { |doc| doc.component }
+  end
+  alias_method :docs, :extract
+
+  def parse_files
+    @files.flat_map { |path| parse_file(path) }.compact
+  end
+
+  def parse_file(path)
+    src = File.read(path)
+    matches = scan(src)
+    return unless matches.length
+    matches.map { |match| create_doc(match, path) }
+  end
+
+  def scan(src)
+    src.scan(@matcher)
+  end
+
+  # must return an instance of Doc
+  def create_doc(match, path)
+    DressCode::Document.new({
+      :component => match[0],
+      :prose => match[1].strip,
+      :path => path,
+      :relative_path => path.gsub(@base_dir, '').gsub(/^\//, '')
+    })
+  end
+
+end
+

data/lib/dress_code/generator.rb

@@ -0,0 +1,61 @@
+require 'mustache'
+require_relative '../dress_code'
+require 'debugger'
+
+class DressCode::Generator
+
+  STATIC = "#{File.dirname(__FILE__)}/../static"
+  TEMPLATE = File.read("#{STATIC}/styleguide.html.mustache")
+
+  def initialize(opts)
+    @out_file = opts[:out_file] || 'styleguide.html'
+    @docs = opts[:docs]
+    @css = opts[:css]
+    @js = opts[:js]
+    @template = opts[:template] || TEMPLATE
+    @inline_css = opts[:dress_code_css].nil? ? true : !!opts[:dress_code_css] 
+    @inline_js = opts[:dress_code_js].nil? ? true : !!opts[:dress_code_js] 
+  end
+
+  def generate
+    write_file(@out_file, Mustache.render(@template, {
+      :docs => map_docs,
+      :css => @css,
+      :js => @js,
+      :dress_code_css => dress_code_css,
+      :dress_code_js => dress_code_js
+    }))
+  end
+
+  def dress_code_css
+    return unless @inline_css
+    File.read("#{STATIC}/base.css") + File.read("#{STATIC}/github.css")
+  end
+
+  def dress_code_js
+    return unless @inline_js
+    File.read("#{STATIC}/docs.js")
+  end
+
+  def map_docs
+    @docs.map { |doc| map_doc(doc) }
+  end
+
+  def map_doc(doc)
+    {
+      :id => "#{doc.component.gsub(' ', '_').downcase}",
+      :prose => doc.to_html,
+      :component => doc.component,
+      :file => doc.relative_path
+    }
+  end
+
+  def write_file(path, content)
+    File.open(path, 'w') do |file|
+      puts "# writing file: #{path}"
+      file.write(content)
+    end
+  end
+
+end
+

data/lib/dress_code/renderer.rb

@@ -0,0 +1,21 @@
+require 'redcarpet'
+require 'pygments'
+require_relative '../dress_code'
+
+class DressCode::Renderer < Redcarpet::Render::HTML
+
+  def block_code(code, language)
+    syntax = Pygments.highlight(code, {
+      lexer: language,
+      options: { encoding: 'utf-8' }
+    })
+    inner = if language == 'html'
+      "#{syntax} <div class='code-rendered'>#{code}</div>"
+    else
+      syntax
+    end
+    "<div class='code-demo'>#{inner}</div>"
+  end
+
+end
+

data/lib/static/base.css

@@ -0,0 +1,70 @@
+#nav {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 200px;
+  bottom: 0;
+  overflow: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+#nav > *:fist-child {
+  height: 100.5%
+}
+
+#nav ul {
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+#nav a {
+  display: block;
+  border-bottom: solid 1px #ccc;
+  padding: 8px 4px;
+  text-decoration: none;
+  background: #fff;
+  color: #454545;
+}
+
+#nav a:hover {
+  background: #f5f5f5;
+}
+
+#nav a.active {
+  background: #0088cc;
+  color: #fff;
+}
+
+
+#docs {
+  border-left: solid 1px;
+  position: absolute;
+  top: 0;
+  left: 200px;
+  right: 0;
+  bottom: 0;
+  overflow: auto;
+  -webkit-overflow-scrolling: touch;
+  background: #ccc;
+}
+
+#docs > article {
+  margin: 40px 20px;
+  padding: 20px;
+  min-height: 60%;
+  box-shadow: 2px 6px 16px rgba(0, 0, 0, 0.5);
+  background: #fff;
+  max-width: 700px;
+}
+
+#docs > article:first-child {
+  border:none;
+}
+
+.code-demo:hover {
+  margin-left: -12px;
+  border-left: solid 4px #0088cc;
+  padding-left: 8px;
+}
+

data/lib/static/docs.js

@@ -0,0 +1,76 @@
+;(function() {
+  var items = document.querySelectorAll('#nav a');
+  var docs = document.getElementById('docs');
+  var articles = [].slice.call(docs.querySelectorAll('article'), 0);
+  var tops;
+
+  var setTops = function() {
+    tops = articles.map(function(header) {
+      return header.offsetTop;
+    });
+    setTimeout(setTops, 1000);
+  };
+
+  var setAnchor = function() {
+    var top = docs.scrollTop + (docs.offsetHeight / 2);
+    var inView;
+    for (var i = 0; i < tops.length; i += 1) {
+      if (tops[i] >= top) break;
+    }
+    setCurrent(i - 1);
+  };
+
+  var setCurrent = (function() {
+    var current;
+    return function(index) {
+      var item = items[index];
+      if (current) current.setAttribute('class', '');
+      item.setAttribute('class', 'active');
+      current = item;
+      var article = articles[index];
+      var id = article.getAttribute('id');
+      article.setAttribute('id', '');
+      location.hash = item.hash
+      article.setAttribute('id', id);
+    }
+  })();
+
+  var throttle = function(func, wait) {
+    var context, args, timeout, throttling, more;
+    var whenDone = debounce(function(){ more = throttling = false; }, wait);
+    return function() {
+      context = this; args = arguments;
+      var later = function() {
+        timeout = null;
+        if (more) func.apply(context, args);
+        whenDone();
+      };
+      if (!timeout) timeout = setTimeout(later, wait);
+      if (throttling) {
+        more = true;
+      } else {
+        func.apply(context, args);
+      }
+      whenDone();
+      throttling = true;
+    };
+  };
+
+  var debounce = function(func, wait) {
+    var timeout;
+    return function() {
+      var context = this, args = arguments;
+      var later = function() {
+        timeout = null;
+        func.apply(context, args);
+      };
+      clearTimeout(timeout);
+      timeout = setTimeout(later, wait);
+    };
+  };
+
+  setTops();
+  docs.addEventListener('scroll', throttle(setAnchor, 100));
+
+})();
+

data/lib/static/github.css

@@ -0,0 +1,61 @@
+.hll { background-color: #ffffcc }
+.c { color: #999988; font-style: italic } /* Comment */
+.err { color: #a61717; background-color: #e3d2d2 } /* Error */
+.k { color: #000000; font-weight: bold } /* Keyword */
+.o { color: #000000; font-weight: bold } /* Operator */
+.cm { color: #999988; font-style: italic } /* Comment.Multiline */
+.cp { color: #999999; font-weight: bold; font-style: italic } /* Comment.Preproc */
+.c1 { color: #999988; font-style: italic } /* Comment.Single */
+.cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */
+.gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
+.ge { color: #000000; font-style: italic } /* Generic.Emph */
+.gr { color: #aa0000 } /* Generic.Error */
+.gh { color: #999999 } /* Generic.Heading */
+.gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
+.go { color: #888888 } /* Generic.Output */
+.gp { color: #555555 } /* Generic.Prompt */
+.gs { font-weight: bold } /* Generic.Strong */
+.gu { color: #aaaaaa } /* Generic.Subheading */
+.gt { color: #aa0000 } /* Generic.Traceback */
+.kc { color: #000000; font-weight: bold } /* Keyword.Constant */
+.kd { color: #000000; font-weight: bold } /* Keyword.Declaration */
+.kn { color: #000000; font-weight: bold } /* Keyword.Namespace */
+.kp { color: #000000; font-weight: bold } /* Keyword.Pseudo */
+.kr { color: #000000; font-weight: bold } /* Keyword.Reserved */
+.kt { color: #445588; font-weight: bold } /* Keyword.Type */
+.m { color: #009999 } /* Literal.Number */
+.s { color: #d01040 } /* Literal.String */
+.na { color: #008080 } /* Name.Attribute */
+.nb { color: #0086B3 } /* Name.Builtin */
+.nc { color: #445588; font-weight: bold } /* Name.Class */
+.no { color: #008080 } /* Name.Constant */
+.nd { color: #3c5d5d; font-weight: bold } /* Name.Decorator */
+.ni { color: #800080 } /* Name.Entity */
+.ne { color: #990000; font-weight: bold } /* Name.Exception */
+.nf { color: #990000; font-weight: bold } /* Name.Function */
+.nl { color: #990000; font-weight: bold } /* Name.Label */
+.nn { color: #555555 } /* Name.Namespace */
+.nt { color: #000080 } /* Name.Tag */
+.nv { color: #008080 } /* Name.Variable */
+.ow { color: #000000; font-weight: bold } /* Operator.Word */
+.w { color: #bbbbbb } /* Text.Whitespace */
+.mf { color: #009999 } /* Literal.Number.Float */
+.mh { color: #009999 } /* Literal.Number.Hex */
+.mi { color: #009999 } /* Literal.Number.Integer */
+.mo { color: #009999 } /* Literal.Number.Oct */
+.sb { color: #d01040 } /* Literal.String.Backtick */
+.sc { color: #d01040 } /* Literal.String.Char */
+.sd { color: #d01040 } /* Literal.String.Doc */
+.s2 { color: #d01040 } /* Literal.String.Double */
+.se { color: #d01040 } /* Literal.String.Escape */
+.sh { color: #d01040 } /* Literal.String.Heredoc */
+.si { color: #d01040 } /* Literal.String.Interpol */
+.sx { color: #d01040 } /* Literal.String.Other */
+.sr { color: #009926 } /* Literal.String.Regex */
+.s1 { color: #d01040 } /* Literal.String.Single */
+.ss { color: #990073 } /* Literal.String.Symbol */
+.bp { color: #999999 } /* Name.Builtin.Pseudo */
+.vc { color: #008080 } /* Name.Variable.Class */
+.vg { color: #008080 } /* Name.Variable.Global */
+.vi { color: #008080 } /* Name.Variable.Instance */
+.il { color: #009999 } /* Literal.Number.Integer.Long */

data/lib/static/styleguide.html.mustache

@@ -0,0 +1,36 @@
+<!doctype html>
+
+<html lang="en">
+  <head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+    <title>Styleguide</title>
+    <style>{{{dress_code_css}}}</style>
+    {{#css}}
+    <link href="{{.}}" rel="stylesheet" charset="utf-8">
+    {{/css}}
+  </head>
+  <body>
+
+  <nav id="nav">
+    <ul>
+      {{#docs}}
+      <li><a href="#{{id}}">{{component}}</a></li>
+      {{/docs}}
+    </ul>
+  </nav>
+
+  <section id="docs">
+    {{#docs}}
+    <article id="{{id}}">
+      <h2>{{component}}</h2>
+      <p><small>Defined in <em>{{file}}</em></small></p>
+      {{{prose}}}
+    </article>
+    {{/docs}}
+  </section>
+
+  {{#js}}
+  <script src="{{.}}"></script>
+  {{/js}}
+  <script>{{{dress_code_js}}}</script>
+

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: dress_code
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Ryan Florence
+- Cameron Matheson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pygments.rb
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mustache
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: colored
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Dress Code extracts comment blocks from your stylesheets and creates
+  a styleguide using your CSS.
+email: 
+executables:
+- dress_code
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/dress_code
+- lib/dress_code/document.rb
+- lib/dress_code/extractor.rb
+- lib/dress_code/generator.rb
+- lib/dress_code/renderer.rb
+- lib/dress_code.rb
+- lib/static/base.css
+- lib/static/docs.js
+- lib/static/github.css
+- lib/static/styleguide.html.mustache
+- LICENSE
+- README.md
+homepage: http://github.com/instructure/dress_code
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: CSS Documentation and Styleguide Generator
+test_files: []
+has_rdoc: