css_doc 0.0.6

data/bin/cssdoc

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'css_doc'
+require 'optparse'
+
+class CSSDocCli
+  def self.run(args)
+    options = {
+      :input_dir => '.',
+      :skip_files => [],
+      :output_dir => 'doc',
+      :template_path => File.expand_path(File.dirname(__FILE__) + "/../src/templates/default")
+    }
+    OptionParser.new do |opts|
+      opts.banner = "Usage: cssdoc [options] [input-dir/input-files]"
+      opts.on("-o", "--output=dir", "Specify output directory") do |dir|
+        options[:output_dir] = dir
+      end
+      opts.on("-s", "--skip=files", "Skip specified files") do |files|
+        options[:skip_files] = files.split(',').collect { |file| file.strip }
+      end
+      opts.on("-p", "--project-name=name", "Specify Project name") do |name|
+        options[:project_name] = name
+      end
+      opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
+        options[:verbose] = v
+      end
+      opts.on("-t", "--template=name/path", "Specify template or template path") do |name|
+        if File.directory?(name)
+          options[:template_path] = name
+        else
+          options[:template_path] = File.expand_path(File.dirname(__FILE__) + "/../src/templates/#{name}")
+        end
+      end
+    end.parse!
+    options[:input_dir] = ARGV.first if ARGV.first
+    
+    driver = CSSDoc::Driver.new
+    driver.run(options)
+  end
+end
+
+CSSDocCli.run(ARGV)

data/src/css_doc.rb

@@ -0,0 +1,16 @@
+require 'csspool'
+
+require File.dirname(__FILE__) + '/css_doc/document'
+require File.dirname(__FILE__) + '/css_doc/document_handler'
+require File.dirname(__FILE__) + '/css_doc/document_collection'
+require File.dirname(__FILE__) + '/css_doc/section'
+require File.dirname(__FILE__) + '/css_doc/rule_set'
+require File.dirname(__FILE__) + '/css_doc/template'
+require File.dirname(__FILE__) + '/css_doc/documentation'
+require File.dirname(__FILE__) + '/css_doc/document_documentation'
+require File.dirname(__FILE__) + '/css_doc/rule_set_documentation'
+require File.dirname(__FILE__) + '/css_doc/section_documentation'
+require File.dirname(__FILE__) + '/css_doc/css_writer'
+require File.dirname(__FILE__) + '/css_doc/driver'
+require File.dirname(__FILE__) + '/css_doc/examples'
+require File.dirname(__FILE__) + '/css_pool/visitors/to_css'

data/src/css_doc/css_writer.rb

@@ -0,0 +1,20 @@
+module CSSDoc
+  class CSSWriter
+    def initialize(collection)
+      @collection = collection
+    end
+    
+    def write
+      output = ""
+      @collection.rule_sets.each do |rule_set|
+        selectors = rule_set.selectors.collect { |selector| 'div.example ' + selector.to_css }
+        output << selectors.join(', ')
+        output << '{'
+        output << rule_set.declaration_css
+        output << '}'
+        output << "\n"
+      end
+      output
+    end
+  end
+end

data/src/css_doc/document.rb

@@ -0,0 +1,31 @@
+module CSSDoc
+  class Document < CSSPool::CSS::Document
+    attr_accessor :documentation
+    attr_accessor :sections
+    attr_accessor :name
+    
+    def self.parse string, name
+      unless string && string.length > 0
+        return CSSDoc::Document.new(name)
+      end
+      handler = CSSDoc::DocumentHandler.new(name)
+      parser = CSSPool::SAC::Parser.new(handler)
+      parser.parse(string)
+      handler.document
+    end
+    
+    def initialize(name)
+      super()
+      @name = name
+      @sections = [Section.new(self, '')]
+    end
+    
+    def output_file_name
+      name.gsub('.css', '_css.html')
+    end
+    
+    def named_sections
+      sections.reject {|section| section.name.nil?}
+    end
+  end
+end

data/src/css_doc/document_collection.rb

@@ -0,0 +1,33 @@
+module CSSDoc
+  class DocumentCollection < CSSPool::CSS::Document
+    attr_accessor :documents
+    
+    def initialize
+      @documents = []
+    end
+    
+    def rule_sets
+      documents.collect { |document| document.rule_sets }.flatten
+    end
+    
+    def selectors
+      rule_sets.collect { |rule_set| rule_set.selectors }.flatten
+    end
+    
+    def sections
+      documents.collect { |document| document.sections }.flatten
+    end
+    
+    def named_sections
+      sections.reject { |section| section.name.nil? }
+    end
+    
+    def selector_hash
+      selectors.inject({}) { |hash, selector| (hash[selector.to_css] ||= []) << selector; hash }
+    end
+    
+    def section_hash
+      named_sections.inject({}) { |hash, section| (hash[section.name] ||= []) << section; hash }
+    end
+  end
+end

data/src/css_doc/document_documentation.rb

@@ -0,0 +1,5 @@
+module CSSDoc
+  class DocumentDocumentation < Documentation
+    define_tag :file, :note, :appdef, :link, :copyright, :author, :css_for, :version, :date, :license
+  end
+end

data/src/css_doc/document_handler.rb

@@ -0,0 +1,36 @@
+module CSSDoc
+  class DocumentHandler < CSSPool::CSS::DocumentHandler
+    def initialize(name)
+      super()
+      @name = name
+    end
+    
+    def start_document
+      @document = CSSDoc::Document.new(@name)
+    end
+
+    def comment(comment)
+      if comment =~ /@file/
+        @document.documentation = DocumentDocumentation.new(comment)
+      elsif comment =~ /@section/
+        @document.sections << Section.new(@document, comment)
+      else
+        @last_comment = comment
+      end
+    end
+
+    def start_selector(selector_list)
+      rule_set = CSSDoc::RuleSet.new(
+        selector_list,
+        [],
+        @media_stack.last || []
+      )
+      rule_set.document = @document
+      rule_set.documentation = RuleSetDocumentation.new(@last_comment =~ /^\*/ ? @last_comment : "")
+      @last_comment = nil
+    
+      @document.rule_sets << rule_set
+      @document.sections.last.rule_sets << rule_set
+    end
+  end
+end

data/src/css_doc/documentation.rb

@@ -0,0 +1,111 @@
+module CSSDoc
+  class Documentation
+    class Section
+      attr_accessor :lines
+      def initialize(lines)
+        self.lines = lines
+      end
+
+      def to_s
+        lines.join("\n")
+      end
+    end
+    
+    class TextSection < Section
+      def to_html
+        result = "<p>"
+        result << lines.collect {|l|l.strip}.join("\n").gsub(/\n\n+/, '</p><p>').gsub(/\n/, ' ').strip
+        result << "</p>"
+        result.gsub('<p></p>', '')
+      end
+    end
+      
+    class CodeSection < Section
+      def to_html
+        result = "<pre>" + lines.join("\n").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', '&quot;') + "</pre>"
+        result << %{<div class="example">#{lines.join("\n")}</div>}
+      end
+    end
+    
+    class Sections < Array
+      def to_html
+        collect {|section| section.to_html}
+      end
+    end
+
+    attr_accessor :comment
+    attr_accessor :sections
+    
+    def self.tags
+      @tags ||= []
+    end
+    
+    def self.define_tag(*names)
+      names.each do |name|
+        attr_accessor name
+        tags << name
+      end
+    end
+    
+    def initialize(comment)
+      @comment = comment
+      @sections = Sections.new
+      parse_documentation
+    end
+    
+    def to_s
+      @comment
+    end
+    
+    def parse_tags(line)
+      self.class.tags.each do |tag|
+        rx = /@#{tag.to_s.gsub('_', '-')}/
+        if line =~ rx
+          instance_variable_set(:"@#{tag}", line.gsub(rx, "").strip)
+          return true
+        end
+      end
+      return false
+    end
+    
+    def parse_comment
+      @parsed_comment ||= comment.gsub(/\*\/$/, '').split("\n").collect { |line| line.gsub(/^\s*\*/, '') }
+    end
+    
+    def parse_documentation
+      lines = parse_comment
+      parse(lines)
+    end
+    
+    def empty?
+      parse_comment.join("\n").strip.empty?
+    end
+  
+    def parse(lines)
+      section_type = TextSection
+      section_text = []
+      lines.each do |line|
+        unless parse_tags(line)
+          if line =~ /@code/
+            sections << section_type.new(section_text)
+            section_text = []
+            section_type = CodeSection
+          elsif line =~ /@endcode/
+            sections << section_type.new(section_text)
+            section_text = []
+            section_type = TextSection
+          elsif line =~ /@description/
+            section_text << line.gsub(/@description/, '')
+          else
+            section_text << line
+          end
+        end
+      end
+      sections << section_type.new(section_text)
+      
+      sections.each do |section|
+        Examples.add(section) if section.is_a?(CodeSection)
+      end
+    end
+  end
+end

data/src/css_doc/driver.rb

@@ -0,0 +1,85 @@
+require 'fileutils'
+
+module CSSDoc
+  class Driver
+    def run(options = {})
+      @options = options
+      
+      @collection = CSSDoc::DocumentCollection.new
+
+      generate_file_documentation
+      generate_index_documentation
+      generate_css
+      copy_additional_files
+    end
+    
+    def generate_file_documentation
+      skip_files = @options[:skip_files] || []
+      
+      Dir.glob("#{@options[:input_dir]}/**/*.css").each do |file_name|
+        relative_path = file_name.gsub("#{@options[:input_dir]}/", '')
+        next if skip_files.include?(relative_path)
+        
+        log "Generating documentation for file #{relative_path} ..."
+
+        FileUtils.mkdir_p("#{@options[:output_dir]}/#{File.dirname(relative_path)}")
+        doc = CSSDoc::Document.parse(File.read(file_name), relative_path)
+        
+        generate(:template => 'document', :file_name => doc.output_file_name, :locals => { :document => doc, :title => doc.name })
+
+        @collection.documents << doc
+      end
+    end
+    
+    def generate_index_documentation
+      log "Generating Selector Index ..."
+      
+      generate(:template => 'selector_index', :locals => { :collection => @collection, :title => 'Selector Index' })
+
+      log "Generating File Index ..."
+
+      generate(:template => 'file_index', :locals => { :collection => @collection, :title => 'File Index' })
+
+      log "Generating Section Index ..."
+
+      generate(:template => 'section_index', :locals => { :collection => @collection, :title => 'Section Index' })
+
+      log "Generating Example Index ..."
+
+      generate(:template => 'example_index', :locals => { :collection => @collection, :title => 'Example Index' })
+
+      log "Generating Index Page ..."
+
+      generate(:template => 'index', :locals => { :project_name => @options[:project_name], :title => 'Index' })
+    end
+    
+    def generate_css
+      log "Generating Example CSS ..."
+
+      writer = CSSDoc::CSSWriter.new(@collection)
+      File.open("#{@options[:output_dir]}/styles.css", 'w') { |file| file.puts writer.write }
+    end
+    
+    def copy_additional_files
+      log "Copying Additional Files ..."
+
+      FileUtils.cp("#{@options[:template_path]}/css_doc.css", "#{@options[:output_dir]}/")
+    end
+    
+    def log(string)
+      puts string if @options[:verbose]
+    end
+    
+  private
+    def generate(params)
+      file_name = params[:file_name] || params[:template]
+      file_name += '.html' unless file_name =~ /\.html$/
+      
+      relative_root = '.'
+      relative_root = (['..'] * File.dirname(file_name).split('/').size).join('/') if file_name =~ /\//
+
+      html = CSSDoc::Template.new(@options.merge(:relative_root => relative_root)).render(params[:template], params[:locals])
+      File.open("#{@options[:output_dir]}/#{file_name}", 'w') { |file| file.puts html }
+    end
+  end
+end

data/src/css_doc/examples.rb

@@ -0,0 +1,12 @@
+module CSSDoc
+  class Examples
+    def self.add(code)
+      @examples ||= []
+      @examples << code
+    end
+    
+    def self.all
+      @examples
+    end
+  end
+end

data/src/css_doc/rule_set.rb

@@ -0,0 +1,14 @@
+module CSSDoc
+  class RuleSet < CSSPool::CSS::RuleSet
+    attr_accessor :document
+    attr_accessor :documentation
+    
+    def selector_css
+      @selector_css ||= selectors.collect { |selector| selector.to_css }.join(", ")
+    end
+    
+    def declaration_css
+      @declaration_css ||= declarations.collect { |declaration| declaration.to_css }.join(' ')
+    end
+  end
+end

data/src/css_doc/rule_set_documentation.rb

@@ -0,0 +1,5 @@
+module CSSDoc
+  class RuleSetDocumentation < Documentation
+    define_tag :name, :formerly, :deprecated
+  end
+end

data/src/css_doc/section.rb

@@ -0,0 +1,17 @@
+module CSSDoc
+  class Section
+    attr_accessor :document
+    attr_accessor :rule_sets
+    attr_accessor :documentation
+    
+    def initialize(document, comment)
+      @document = document
+      @rule_sets = []
+      @documentation = SectionDocumentation.new(comment)
+    end
+    
+    def name
+      documentation.section
+    end
+  end
+end