pdoc 0.2.0

data/README.markdown

@@ -0,0 +1,34 @@
+PDoc
+====
+
+PDoc is an inline comment parser and JavaScript documentation generator written in Ruby. It is designed for documenting [Prototype](http://prototypejs.org) and Prototype-based libraries.
+
+PDoc uses [Treetop](http://treetop.rubyforge.org/), a Ruby-based DSL for text parsing and interpretation, and its own ActionView-inspired, ERB-based templating system for HTML generation. Other documentation generators (e.g., DocBook XML) are planned.
+
+Unlike other inline-doc parsers, PDoc does not rely on the JavaScript source code at all; it only parses the comments. This approach, though slightly more verbose, is much better at generating consistent, reliable documentation, and avoids the headaches encountered when documenting highly dynamic languages.
+
+## Installation
+
+PDoc depends on Rake, your choice of markdown parser, and treetop, all of which can be obtained through RubyGems:
+
+    gem install rake bluecloth treetop
+    
+## Usage
+
+For hints on how to run PDoc on the command line, consult the built-in Rake tasks (in `Rakefile`) and the `PDoc::Runner` class (in `lib/pdoc/runner.rb`).
+
+## How it works
+
+The process of turning inline PDoc comments into a human-friendly document has two phases.
+
+### Parsing phase
+In this phase, the source files are scanned for PDoc comments, then parsed with the Ruby files generated from the Treetop language grammar. The product of this phase is a tree full of specialized classes, all of which inherit from `Treetop::Runtime::SyntaxNode`.
+
+The root of the tree is an instance of `Documentation::Doc`. It comprises one or more instances of `Documentation::Section`; which in turn comprise language elements like namespaces, classes, constants, etc., all of which have class representations.
+
+### Rendering phase
+Next, PDoc asks a _generator_ how to translate this abstract tree into a hierarchical document. The default generator outputs organized HTML in a manner similar to [RDoc](http://rdoc.sourceforge.net/ "RDoc - Document Generator for Ruby Source")'s.
+
+The HTML generator (`PDoc::Generators::Html`) has associated _templates_ (in the `templates` directory) that accept syntax nodes and echo their metadata onto the page using [ERB](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/index.html "erb: Ruby Standard Library Documentation"). Templates are modular, so it's quite easy to apply a custom "skin" to one's documentation pages.
+
+Furthermore, generators themselves are modular; PDoc can, theoretically, parse once and render to several different targets (HTML, [DocBook XML](http://www.docbook.org/ "DocBook.org"), CHM, PDF, even [ScriptDoc](http://www.scriptdoc.org/ "ScriptDoc.org: Dynamic Language Documentation").) We hope many such generators will exist in the future.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rake'
+require 'lib/pdoc'
+
+desc "Builds the documentation"
+task :build_doc do
+  PDoc.run({
+    :source_files => [File.join(File.dirname(__FILE__), "test", "fixtures", "ajax.js")],
+    :destination => OUTPUT_DIR,
+    :syntax_highlighter => :pygments,
+    :markdown_parser => :bluecloth,
+    :src_code_href => proc { |file, line|
+      "http://github.com/example/ex/#{file}##{line}"
+    },
+    :pretty_urls => false,
+    :bust_cache => true,
+    :name => 'Example JavaScript Framework',
+    :short_name => 'Ex',
+    :home_url => 'http://example.com',
+    :doc_url => 'http://example.com/api',
+    :version => "1.2.0",
+    :copyright_notice => 'This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0 Unported License</a>.' 
+  })
+end
+
+desc "Empties output directory"
+task :remove_doc do
+  rm_rf Dir.glob(File.join(OUTPUT_DIR, "*"))
+end
+
+desc "Empties the output directory and builds the documentation."
+task :doc => [:remove_doc, :build_doc]
+
+desc "Runs all the unit tests."
+task :test do 
+  require 'rake/runtest'
+  Rake.run_tests '**/*_test.rb'
+end
+
+task :compile_parser do
+  require 'treetop'
+  compiler = Treetop::Compiler::GrammarCompiler.new
+  treetop_dir = File.expand_path(File.join(File.dirname(__FILE__), "lib", "pdoc", "parser", "treetop_files"))
+  Dir.glob(File.join(treetop_dir, "*.treetop")).each do |treetop_file_path|
+    compiler.compile(treetop_file_path)
+  end
+end

data/bin/pdoc

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'oyster'
+require File.dirname(__FILE__) + '/../lib/pdoc'
+
+spec = Oyster.spec do
+  name "pdoc -- Inline comment parser and JavaScript documentation generator"
+  author "Tobie Langel <tobie.langel@gmail.com>"
+  
+  synopsis <<-EOS
+    pdoc [-o OUTPUT_DIR] [-t TEMPLATE_DIR] SOURCE_FILES
+    pdoc [OPTIONS] -d SOURCE_DIRECTORY
+  EOS
+  
+  string :directory,
+         :desc => "Directory to search for JavaScript files. Will take all *.js " +
+                  "files from the given directory (including subdirectories) and use " +
+                  "them to generate documentation. This option takes precedence over " +
+                  "SOURCE_FILES."
+  
+  string :output,
+         :desc => "Directory in which to dump output files",
+         :default => "pdoc"
+  
+  string :templates,
+         :desc => "Directory containing template files"
+  
+  subcommand :'copy-templates' do
+    synopsis <<-EOS
+      pdoc copy-templates TYPE DESTINATION
+    EOS
+    
+    description <<-EOS
+      PDoc includes a set of default templates for each type of output generator.
+      This command lets you extract a set of these templates into a local directory
+      so you can tweak it to suit your needs. Be sure to specify your set of
+      templates next time you run pdoc.
+    EOS
+  end
+end
+
+begin; options = spec.parse
+rescue Oyster::HelpRendered; exit
+end
+
+if command = options[:'copy-templates']
+  args = command[:unclaimed]
+  PDoc.copy_templates(args[0], File.expand_path(args[1]))
+  exit
+end
+
+files = (d = options[:directory]) ?
+        Dir["#{d}/**/*.js"].map(&File.method(:expand_path)) :
+        options[:unclaimed].dup
+
+files << {:destination => options[:output], :templates => options[:templates]}
+PDoc::Runner.new(*files).run
+

data/lib/pdoc.rb

@@ -0,0 +1,32 @@
+DIR = File.expand_path(File.dirname(__FILE__))
+OUTPUT_DIR    = File.join(DIR, '..', 'output')
+TEMPLATES_DIR = File.join(DIR, '..', 'templates')
+VENDOR_DIR    = File.join(DIR, '..', 'vendor')
+PARSER_DIR    = File.join(DIR, 'pdoc', 'parser')
+
+[DIR, VENDOR_DIR, PARSER_DIR, OUTPUT_DIR, TEMPLATES_DIR].each do |c|
+  $:.unshift(c)
+end
+
+require 'rubygems'
+require 'erb'
+require 'fileutils'
+
+require 'pdoc/error'
+require 'pdoc/runner'
+require 'pdoc/generators'
+require 'pdoc/parser'
+require 'pdoc/models'
+require 'pdoc/treemaker'
+
+module PDoc
+  def self.run(options = {})
+    Runner.new(options.dup).run
+  end
+  
+  def self.copy_templates(template_type, destination)
+    dir = File.expand_path(destination)
+    raise "File already exists: #{destination}" if File.exist?(dir)
+    FileUtils.cp_r("#{TEMPLATES_DIR}/#{template_type}", dir)
+  end
+end

data/lib/pdoc/error.rb

@@ -0,0 +1,4 @@
+module PDoc
+  class PDocError < StandardError
+  end
+end

data/lib/pdoc/generators.rb

@@ -0,0 +1,6 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'generators', 'abstract_generator'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'generators', 'html'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'generators', 'pythonesque'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'generators', 'json'))
+
+

data/lib/pdoc/generators/abstract_generator.rb

@@ -0,0 +1,16 @@
+module PDoc
+  module Generators
+    class AbstractGenerator
+      attr_reader :options, :root
+      def initialize(root, options = {})
+        @root = root
+        @options = options
+      end
+      
+      # Creates a new directory with read, write and execute permission.
+      def mkdir(name)
+        Dir.mkdir(name, 0755)
+      end
+    end
+  end
+end

data/lib/pdoc/generators/html.rb

@@ -0,0 +1,8 @@
+HTML_DIR = File.expand_path(File.join(File.dirname(__FILE__), "html"))
+
+require File.join(HTML_DIR, "helpers")
+require File.join(HTML_DIR, "template")
+require File.join(HTML_DIR, "page")
+require File.join(HTML_DIR, "website")
+require File.join(HTML_DIR, "syntax_highlighter")
+

data/lib/pdoc/generators/html/helpers.rb

@@ -0,0 +1,256 @@
+module PDoc
+  module Generators
+    module Html
+      module Helpers
+        module BaseHelper
+          def content_tag(tag_name, content, attributes = {})
+            "<#{tag_name}#{attributes_to_html(attributes)}>#{content}</#{tag_name}>"
+          end
+
+          def img_tag(filename, attributes = {})
+            attributes.merge! :src => "#{path_prefix}images/#{filename}"
+            tag(:img, attributes)
+          end
+
+          def tag(tag_name, attributes = {})
+            "<#{tag_name}#{attributes_to_html(attributes)} />"
+          end
+          
+          def link_to(name, path, attributes={})
+            content_tag(:a, name, attributes.merge(:href => path))
+          end
+          
+          def htmlize(markdown)
+            markdown = Website.syntax_highlighter.parse(markdown)
+            Website.markdown_parser.new(markdown).to_html
+          end
+          
+          # Gah, what an ugly hack.
+          def inline_htmlize(markdown)
+            htmlize(markdown).gsub(/^<p>/, '').gsub(/<\/p>$/, '')
+          end
+          
+          def javascript_include_tag(*names)
+            names.map do |name|
+              attributes = {
+                :src => "#{path_prefix}javascripts/#{name}.js",
+                :type => "text/javascript",
+                :charset => "utf-8"
+              }
+              content_tag(:script, "", attributes)
+            end.join("\n")
+          end
+
+          def stylesheet_link_tag(*names)
+            names.map do |name|
+              attributes = {
+                :href => "#{path_prefix}stylesheets/#{name}.css",
+                :type => "text/css",
+                :media => "screen, projection",
+                :charset => "utf-8",
+                :rel => "stylesheet"
+              }
+              tag(:link, attributes)
+            end.join("\n")
+          end
+          
+          private
+            def attributes_to_html(attributes)
+              attributes = attributes.sort { |a, b| a.to_s <=> b.to_s }
+              attributes.map do |a|
+                k, v = a
+                k ? " #{k}=\"#{v}\"" : ""
+              end.join
+            end
+        end
+        
+        module LinkHelper
+          def path_prefix
+            "../" * depth
+          end
+          
+          def path_to(obj)
+            path = path_prefix << obj.url << '/'
+            Website.pretty_urls? ? path : "#{path}index.html"
+          end
+          
+          def auto_link(obj, options = {})
+            if obj.is_a?(String)
+              original = obj
+              obj = root.find(obj)
+              return original unless obj
+            end
+            name = options.delete(:name) == :short ? obj.name : obj.full_name
+            if obj.type == 'section'
+              title = obj.full_name
+            else
+              title = "#{obj.full_name} (#{obj.type})"
+            end
+            link_to(name, path_to(obj), { :title => title }.merge(options))
+          end
+          
+          def auto_link_code(obj, options = {})
+            "<code>#{auto_link(obj, options)}</code>"
+          end
+
+          def auto_link_content(content)
+            return '' if content.nil?
+            content.gsub!(/\[\[([a-zA-Z]+)\s+section\]\]/) do |m|
+              result = auto_link(root.find($1), :name => :long)
+              result
+            end
+            content.gsub(/\[\[([a-zA-Z$\.#]+)(?:\s+([^\]]+))?\]\]/) do |m|
+              if doc_instance = root.find($1)
+                $2 ? link_to($2, path_to(doc_instance)) : auto_link_code(doc_instance, :name => :long)
+              else
+                $1
+              end
+            end
+          end
+          
+          def auto_link_types(types, options = {})
+            types = types.split(/\s+\|\s+/) if types.is_a?(String)
+            types.map do |t|
+              if match = /^\[([\w\d\$\.\(\)#]*[\w\d\$\(\)#])...\s*\]$/.match(t) # e.g.: [Element...]
+                "[#{auto_link(match[1], options)}…]"
+              else
+                auto_link(t, options)
+              end
+            end
+          end
+          
+          def dom_id(obj)
+            "#{obj.id}-#{obj.type.gsub(/\s+/, '_')}"
+          end
+        end
+        
+        module CodeHelper
+          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_full_name(obj)
+            obj.full_name.sub(/\.([^.]+)$/, '#\1')
+          end
+          
+          def method_synopsis(object)
+            result = []
+            object.signatures.each do |signature|
+              if return_value = signature.return_value
+                types = auto_link_types(return_value, :name => :long).join(' | ')
+                result << "#{signature.name} &rarr; #{types}"
+              else # Constructors
+                result << signature.name
+              end
+            end
+            result
+          end
+          
+          def breadcrumb(obj, options = {})
+            options = {:name => :short}.merge(options)
+            result = []
+            begin
+              result << auto_link(obj, options.dup)
+              obj = obj.parent
+            end until obj.is_a?(Models::Root)
+            result.reverse!
+          end
+        end
+        
+        module MenuHelper
+          NODES = [
+            :namespaces,
+            :classes,
+            :mixins,
+            :utilities
+          ]
+          LEAVES = [
+            :constants,
+            :class_methods,
+            :class_properties,
+            :instance_methods,
+            :instance_properties
+          ]
+          
+          def menu(obj)
+            if obj.parent
+              html = menu_item(obj, :name => :long)
+            
+              html << node_submenu(obj)
+            
+              if obj == doc_instance && obj.respond_to?(:constants)
+                html << leaf_submenu(obj)
+              elsif doc_instance && doc_instance.respond_to?(:parent)
+                parent = doc_instance.parent
+                html << leaf_submenu(parent) if parent == obj && obj.respond_to?(:constants)
+              end
+            
+              content_tag(:li, html)
+            else #root
+              node_submenu(obj)
+            end
+          end
+          
+          def node_submenu(obj)
+            children = []
+            options = {}
+            
+            NODES.each do |prop|
+              children.concat(obj.send(prop)) if obj.respond_to?(prop)
+            end
+            
+            list_items = children.sort.map { |item| menu(item) }
+            if obj.respond_to?(:sections)
+              obj.sections.each { |section| list_items << menu(section) }
+              options[:class] = "menu-items"
+              options[:id] = "api_menu"
+            elsif obj.type == "section"
+              options[:class] = "menu-section"
+            end
+            list_items.empty? ? '' : content_tag(:ul, list_items.join("\n"), options)
+          end
+          
+          def menu_item(obj, options = {})
+            options = options.dup
+            options[:class] = class_names_for(obj, options)
+            content_tag(:div, auto_link(obj, options), :class => 'menu-item')
+          end
+          
+          def leaf_submenu(obj)
+            items = []
+            if obj.respond_to?(:constructor) && obj.constructor
+              items << content_tag(:li, menu_item(obj.constructor, :name => :short))
+            end
+            LEAVES.each do |prop|
+              if obj.respond_to?(prop)
+                obj.send(prop).sort!.map do |item|
+                  items << content_tag(:li, menu_item(item, :name => :short))
+                end
+              end
+            end
+            content_tag(:ul, items.join("\n"))
+          end
+          
+          def class_names_for(obj, options = {})
+            classes = []
+            classes << obj.type.gsub(/\s+/, '-')
+            classes << "deprecated" if obj.deprecated?
+            if doc_instance
+              if obj == doc_instance
+                classes << "current"
+              elsif obj.ancestor_of?(doc_instance)
+                classes << "current-parent"
+              end
+            end
+            classes.join(' ')
+          end
+        end
+      end
+    end
+  end
+end