pdoc 0.2.0

data/lib/pdoc/parser/treetop_files/description.treetop

@@ -0,0 +1,7 @@
+grammar Description
+  include Basic
+  
+  rule text
+    (blank_line / text_line)* <Text>
+  end
+end

data/lib/pdoc/parser/treetop_files/documentation.treetop

@@ -0,0 +1,75 @@
+grammar Documentation
+  include Tags
+  include Events
+  include ArgumentDescription
+  include Description
+  include SectionContent
+  include EbnfExpression
+  
+  rule documentation
+    ((!comment_start .)* doc_instance)+ (!comment_start .)* <Doc> / (!comment_start .)* {
+      def each
+      end
+    }
+  end
+  
+  rule doc_instance
+    section_doc / klass_method_doc / instance_method_doc / klass_property_doc / instance_property_doc / utility_doc / constructor_doc / klass_doc / mixin_doc / constant_doc / namespace_doc
+  end
+  
+  rule section_doc
+    start section comment_end <Section>
+  end
+  
+  rule constructor_doc
+    start ebnf:(line constructor)+ argument_descriptions events text comment_end <Constructor>
+  end
+  
+  rule mixin_doc
+    start line ebnf:mixin text comment_end <Mixin>
+  end
+  
+  rule klass_doc
+    start line space* ebnf:klass text comment_end <Klass>
+  end
+
+  rule klass_method_doc
+    start ebnf:(line klass_method)+ argument_descriptions events text comment_end <KlassMethod>
+  end
+  
+  rule instance_method_doc
+    start ebnf:(line instance_method)+ argument_descriptions events text comment_end <InstanceMethod>
+  end
+  
+  rule klass_property_doc
+    start line ebnf:klass_property text comment_end <KlassProperty>
+  end
+  
+  rule instance_property_doc
+    start line ebnf:instance_property text comment_end <InstanceProperty>
+  end
+
+  rule constant_doc
+    start line ebnf:constant text comment_end <Constant>
+  end
+  
+  rule utility_doc
+    start ebnf:(line utility)+ argument_descriptions events text comment_end <Utility>
+  end
+  
+  rule namespace_doc
+    start line space* ebnf:namespace text comment_end <Namespace>
+  end
+  
+  rule start
+    comment_start space* (tags)?
+  end
+  
+  rule argument_descriptions
+    (argument_description+ blank_line)?
+  end
+  
+  rule events
+    (super)?
+  end
+end

data/lib/pdoc/parser/treetop_files/ebnf_arguments.treetop

@@ -0,0 +1,33 @@
+grammar EbnfArguments
+  include EbnfJavascript
+
+  rule arguments
+    first_argument:argument rest:(argument_separator argument)* <Arguments>
+    /
+    space* {
+      def to_a
+        []
+      end
+    }
+  end
+
+  rule argument
+    optional_argument / required_argument
+  end
+
+  rule argument_separator
+    space* (&'[' / ',')
+  end
+
+  rule optional_argument
+    "[" space* ","? required_argument default:(default_value?) nested:(optional_argument*) "]" <OptionalArgument> 
+  end
+
+  rule default_value
+    space* "=" space* value:[^\[\]]+ 
+  end
+
+  rule required_argument
+    space* (js_variable / js_object) '...'? space* <Argument>
+  end
+end

data/lib/pdoc/parser/treetop_files/ebnf_expression.treetop

@@ -0,0 +1,70 @@
+grammar EbnfExpression
+  include EbnfArguments
+  rule ebnf
+    klass_method / instance_method / klass_property / instance_property / utility / constructor / mixin / klass / constant / namespace 
+  end
+  
+  rule mixin
+    space* 'mixin' space+ js_namespace  (includes)? <Mixin>
+  end
+  
+  rule klass
+    space* 'class' space+ js_namespace extends:(space+ '<' space+ js_namespace)? (includes)? <Klass>
+  end
+  
+  rule includes
+    line space* 'includes' space+ js_namespace more:(',' space+ js_namespace)*
+  end
+  
+  rule constructor
+    space* 'new' (space)+ js_namespace args <Constructor>
+  end
+  
+  rule instance_accessor
+    js_namespace '#' js_variable
+  end
+  
+  rule instance_signature
+    instance_accessor args
+  end
+
+  rule klass_method
+    space* js_namespace args return_value <KlassMethod>
+  end
+  
+  rule instance_method
+    space* instance_signature return_value <InstanceMethod>
+  end
+  
+  rule klass_property
+    space* js_namespace return_value <KlassProperty>
+  end
+  
+  rule instance_property
+    space* instance_accessor return_value <InstanceProperty>
+  end
+
+  rule constant
+    space* js_namespace space* "=" space* value:(char)+ space* <Constant>
+  end
+  
+  rule utility
+    space* utility_name:('$' [$a-zA-Z]*) args return_value <Utility>
+  end
+  
+  rule args
+    '(' space* methodize:'@'? arguments space* ')' {
+      def text_value
+        super.to_s.sub('( )', '()')
+      end
+    }
+  end
+
+  rule namespace
+    js_namespace (includes)? <Namespace>
+  end
+
+  rule return_value
+    space* '->' space* value:(char)+
+  end
+end

data/lib/pdoc/parser/treetop_files/ebnf_javascript.treetop

@@ -0,0 +1,54 @@
+grammar EbnfJavascript
+  include Basic
+  rule primitive
+    js_all_caps_constant / js_namespace / js_constant  / js_variable / js_object
+  end
+  
+  rule js_object
+    '{' [^}]* '}'
+  end
+  
+  rule js_constant
+    [A-Z] [a-zA-Z_0-9$]* {
+      def value
+        text_value
+      end
+    }
+  end
+
+  rule js_all_caps_constant
+    [A-Z] [A-Z_]+ {
+      def value
+        text_value
+      end
+    }
+  end
+  
+  rule js_variable
+    [_a-zA-Z] [_a-zA-Z0-9]* {
+      def value
+        text_value
+      end
+    }
+  end
+  
+  rule js_namespace
+    (js_constant / js_all_caps_constant / js_variable) ('.' (js_constant / js_all_caps_constant / js_variable))* {
+      def namespace
+        to_a.slice(0..-2).join(".")
+      end
+    
+      def name
+        to_a.pop
+      end
+    
+      def to_a
+        text_value.split('.')
+      end
+      
+      def full_name
+        text_value
+      end
+    }
+  end
+end

data/lib/pdoc/parser/treetop_files/events.treetop

@@ -0,0 +1,17 @@
+grammar Events
+  include Basic
+  
+  rule events
+    line space* 'fires' space+ event more:(',' space* event)* {
+      def to_a
+        [event.text_value].concat(more.elements.map{ |e| e.event.text_value })
+      end
+    }
+  end
+  
+  rule event
+    [a-zA-Z]+ (':' [a-zA-Z]+)*
+  end
+end
+
+

data/lib/pdoc/parser/treetop_files/section_content.treetop

@@ -0,0 +1,8 @@
+grammar SectionContent
+  include Basic
+  include Description
+  
+  rule section
+    line space* '==' space* title:[a-zA-Z0-9\s]+ space* '==' space* text <Section>
+  end
+end

data/lib/pdoc/parser/treetop_files/tags.treetop

@@ -0,0 +1,31 @@
+grammar Tags
+  include Basic
+  
+  rule tags
+    tag more:(', ' tag)* <Tags>
+  end
+
+  rule tag
+    tag_name opt:(": " tag_value)? {
+      def name
+        tag_name.text_value
+      end
+    
+      def value
+        if opt.respond_to?("tag_value")
+          opt.tag_value.text_value
+        else
+          nil
+        end
+      end
+    }
+  end
+  
+  rule tag_value
+    (![\n:,] .)+
+  end
+  
+  rule tag_name
+    (![\n:,] .)+
+  end
+end

data/lib/pdoc/runner.rb

@@ -0,0 +1,110 @@
+module PDoc
+  require 'yaml'
+  
+  class Runner
+    def initialize(*source_files)
+      options              = source_files.last.is_a?(Hash) ? source_files.pop : {}
+      @source_files        = source_files.empty? ? options[:source_files] : source_files
+      @output_directory    = File.expand_path(options.delete(:destination) || OUTPUT_DIR)
+      @generator           = options.delete(:generator) || Generators::Html::Website
+      @parser              = Parser
+      @serializer          = Serializer
+      @bust_cache          = options.delete(:bust_cache) || false
+      Models.src_code_href = options.delete(:src_code_href)
+      Models.doc_href = options.delete(:doc_href)
+      @generator_options = options
+    end
+    
+    def serialize(files)
+      files.each do |path|
+        File.open(pdoc_file(path), "w+") do |f|
+          f << serialize_file(path)
+        end
+      end
+    end
+    
+    def deserialize(files)
+      results = []
+      files.each do |file|
+        file = pdoc_file(file)
+        File.open(file) do |y|
+          YAML.load_documents(y) { |doc| results << doc }
+        end
+      end
+      results
+    end
+    
+    def new_files
+      @source_files.select do |path|
+        pdoc = pdoc_file(path)
+        !File.exist?(pdoc) || File.mtime(path) > File.mtime(pdoc)
+      end
+    end
+    
+    def run
+      opts = @generator_options
+      puts
+      puts "    Markdown parser:     #{opts[:markdown_parser]}" if opts[:markdown_parser]
+      puts "    Syntax highlighter:  #{opts[:syntax_highlighter]}" if opts[:syntax_highlighter]
+      puts "    Pretty urls:         #{opts[:pretty_urls]}" if opts[:pretty_urls]
+      puts "    Index page:          #{opts[:index_page]}" if opts[:index_page]
+      puts "    Output directory:    #{@output_directory}\n\n"
+      
+      files = @bust_cache ? @source_files : new_files
+      if files.empty?
+        puts "    Restoring serialized documentation from cache.\n\n"
+      else
+        puts "    Parsing JS files for PDoc comments:"
+        start_time = Time.new
+        serialize(files)
+        puts "    Finished parsing files in #{Time.new - start_time} seconds.\n\n"
+      end
+
+      
+      start_time = Time.new
+      data = deserialize(@source_files)
+      root = Treemaker.new(data).root
+      puts "    Building documentation tree. Finished in #{Time.new - start_time} seconds.\n\n"
+      
+      start_time = Time.new
+      puts "    Generating documentation:"
+      @generator.new(root, @generator_options).render(@output_directory)
+      puts "\n    Finished generating documentation in #{Time.new - start_time} seconds.\n\n"
+    end
+    
+    private
+      def serialize_file(path)
+        serializer = @serializer.new
+        serializer.path = path
+        puts "        Parsing #{path}..."
+        File.open(path) do |file|
+          @parser.new(file.read).parse.each do |fragment|
+            fragment.serialize(serializer)
+          end
+        end
+        serializer
+      end
+
+      def pdoc_file(path)
+        name = '.' << File.basename(path, '.js') << '.pdoc.yaml'
+        File.expand_path(File.join(File.dirname(path), name))
+      end
+  end
+  
+  class Serializer
+    attr_accessor :path
+    def initialize
+      @doc_fragments = []
+    end
+    
+    def <<(fragment)
+      fragment = "---\n#{fragment}"
+      fragment << "\nfile: #{path}"
+      @doc_fragments << fragment
+    end
+    
+    def to_s
+      @doc_fragments.join("\n\n")
+    end
+  end
+end

data/lib/pdoc/treemaker.rb

@@ -0,0 +1,94 @@
+module PDoc
+  class Treemaker
+    include Models
+    
+    def initialize(doc_fragments = [])
+      methodized = []
+      doc_fragments.each do |attributes|
+        if attributes['methodized']
+          dups = attributes.dup
+          dups['id'] = methodize_id(dups['id'])
+          dups['type'] = 'instance method'
+          if dups['signatures']
+            dups['signatures'] = dups['signatures'].map do |s|
+              {
+                'signature' => methodize_signature(s['signature']),
+                'return_value' => s['return_value']
+              }
+            end
+          end
+          if dups['alias_of']
+            dups['alias_of'] = methodize_id(dups['alias_of'])
+          end
+          methodized << dups
+          i = instantiate_from(dups)
+          c = instantiate_from(attributes)
+          i.functionalized_self = c
+          c.methodized_self = i
+        else
+          instantiate_from(attributes)
+        end
+      end
+
+      doc_fragments.concat(methodized).each do |attributes|
+        if parent_id = attributes['parent_id']
+          parent = root.find(parent_id)
+          raise "Undocumented object: #{parent_id}." unless parent
+        else
+          parent = root
+        end
+        object = root.find(attributes['id'])
+        object.parent = parent
+        object.attach_to_parent(parent)
+        
+        if superclass_id = attributes['superclass_id']
+          superclass = root.find(superclass_id)
+          raise "Undocumented object: #{superclass_id}." unless superclass
+          object.superclass = superclass
+          superclass.subclasses << object
+        end
+        
+        if included = attributes['included']
+          included.each do |id|
+            mixin = root.find(id)
+            raise "Undocumented object: #{id}." unless mixin
+            object.included_mixins << mixin
+          end
+        end
+        
+        if alias_of_id = attributes['alias_of']
+          alias_of = root.find(alias_of_id)
+          raise "Undocumented object: #{alias_of_id}." unless alias_of
+          object.alias = alias_of
+          alias_of.aliases << object
+        end
+      end
+    end
+    
+    def instantiate_from(attributes)
+      arguments = attributes.delete('arguments')
+      signatures = attributes.delete('signatures')
+      object = Base.instantiate(attributes)
+      arguments.each { |a| Argument.new(a).attach_to_parent(object) } if arguments
+      signatures.each { |s| Signature.new(s).attach_to_parent(object) } if signatures
+      object.register_on(root.registry)
+    end
+    
+    def methodize_signature(sig)
+      sig.sub(/\.([\w\d\$]+)\((.*?)(,\s*|\))/) do
+        first_arg = $2.to_s.strip
+        prefix = first_arg[-1, 1] == '[' ? '([' : '('
+        rest = $3 == ')' ? $3 : ''
+        "##{$1}#{prefix}#{rest}"
+      end
+    end
+    
+    def methodize_id(id)
+      id.sub(/\.([^\.]+)$/) { "##{$1}" }
+    end
+    
+    def root
+      @root ||= Root.new
+    end
+  end
+end