pdoc 0.2.0

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

@@ -0,0 +1,71 @@
+module PDoc
+  module Generators
+    module Html
+      class Page
+
+        include Helpers::BaseHelper
+        include Helpers::LinkHelper
+        
+        def initialize(template, layout, variables = {})
+          @template = template
+          @layout = layout
+          assign_variables(variables)
+        end
+        
+        # Renders the page as a string using the assigned layout.
+        def render
+          if @layout
+            @content_for_layout = Template.new(@template, @templates_directory).result(binding)
+            Template.new(@layout, @templates_directory).result(binding)
+          else
+            Template.new(@template, @templates_directory).result(binding)
+          end
+        end
+        
+        # Creates a new file and renders the page to it
+        # using the assigned layout.
+        def render_to_file(filename)
+          filename ||= ""
+          FileUtils.mkdir_p(File.dirname(filename))
+          File.open(filename, "w+") { |f| f << render }
+        end
+        
+        def include(path, options = {})
+          r = ''
+          options.each { |k, v| r << "#{k.to_s} = options[:#{k}];" }
+          eval(r)
+          
+          if options[:collection]
+            options[:collection].map { |object| Template.new(path, @templates_directory).result(binding) }.join("\n")
+          else
+            Template.new(path, @templates_directory).result(binding)
+          end
+        end
+        
+        private
+          def assign_variables(variables)
+            variables.each { |key, value| instance_variable_set("@#{key}", value) }
+          end
+      end
+
+      class DocPage < Page
+        include Helpers::LinkHelper, Helpers::CodeHelper, Helpers::MenuHelper
+        
+        attr_reader :doc_instance, :depth, :root
+        
+        def initialize(template, layout = "layout", variables = {})
+          if layout.is_a?(Hash)
+            variables = layout
+            layout = "layout"
+          end
+          super(template, layout, variables)
+        end
+        
+        def htmlize(markdown)
+          super(auto_link_content(markdown))
+        end
+      end
+      
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+module PDoc
+  module Generators
+    module Html
+      class SyntaxHighlighter
+        CODE_BLOCK_REGEXP = /(?:\n\n|\A)(?:\s{4,}lang(?:uage)?:\s*(\w+)\s*\n)?((?:\s{4}.*\n*)+)(^\s{0,3}\S|\z)?/
+        
+        attr_reader :highlighter
+        
+        def initialize(h = nil)
+          @highlighter = h.nil? ? :none : h.to_sym
+        end
+        
+        def parse(input)
+          input.gsub(CODE_BLOCK_REGEXP) do |block|
+            language, codeblock, remainder = $1, $2, $3
+            codeblock = codeblock.gsub(/^\s{4}/, '').rstrip
+            "\n\n#{highlight_block(codeblock, language)}\n#{remainder}"
+          end
+        end
+        
+        def highlight_block(code, language)
+          language = :javascript if language.nil?
+          case highlighter.to_sym
+            when :none
+              require 'cgi'
+              code = CGI.escapeHTML(code)
+              "<pre><code class=\"#{language}\">#{code}</code></pre>"
+            when :coderay
+              require 'coderay'
+              CodeRay.scan(code, language).div
+            when :pygments
+              require 'albino'
+              Albino.new(code, language).colorize
+          else
+            raise "Requested unsupported syntax highlighter: #{highlighter}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+begin
+  require 'erubis'
+rescue LoadError
+end
+
+module PDoc
+  module Generators
+    module Html
+      class Template
+        def initialize(file_name = "layout.erb", templates_directory = nil)
+          @file_name = file_name
+          @templates_directory = templates_directory
+          @template = create_template(IO.read(file_path))
+        end
+        
+        def result(binding)
+          @template.result(binding)
+        end
+        
+        private
+          def file_path
+            @file_name << '.erb' unless @file_name =~ /\.erb$/
+            path = File.join(@templates_directory, @file_name.split("/"))
+            File.expand_path(path, DIR)
+          end
+          
+          def create_template(input)
+            if defined?(Erubis)
+              Erubis::Eruby.new(input)
+            else
+              ERB.new(input, nil, '%')
+            end
+          end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+module PDoc
+  module Generators
+    module Html
+      
+      unless defined? TEMPLATES_DIRECTORY
+        TEMPLATES_DIRECTORY = File.join(TEMPLATES_DIR, "html")
+      end
+      
+      class Website < AbstractGenerator
+        
+        include Helpers::BaseHelper
+        include Helpers::LinkHelper
+        
+        class << Website
+          attr_accessor :syntax_highlighter
+          attr_accessor :markdown_parser
+          def pretty_urls?
+            !!@pretty_urls
+          end
+          
+          def pretty_urls=(boolean)
+            @pretty_urls = boolean
+          end
+        end
+        attr_reader :templates_directory, :custom_assets, :index_page
+        def initialize(parser_output, options = {})
+          super
+          @templates_directory = File.expand_path(options[:templates] || TEMPLATES_DIRECTORY)
+          @index_page = options[:index_page] && File.expand_path(options[:index_page])
+          @custom_assets = @options[:assets] && File.expand_path(@options[:assets])
+          self.class.syntax_highlighter = SyntaxHighlighter.new(options[:syntax_highlighter])
+          self.class.pretty_urls = options[:pretty_urls]
+          set_markdown_parser(options[:markdown_parser])
+          load_custom_helpers
+        end
+        
+        def set_markdown_parser(parser = nil)
+          parser = :rdiscount if parser.nil?
+          case parser.to_sym
+          when :rdiscount
+            require 'rdiscount'
+            self.class.markdown_parser = RDiscount
+          when :bluecloth
+            require 'bluecloth'
+            self.class.markdown_parser = BlueCloth
+          when :maruku
+            require 'maruku'
+            self.class.markdown_parser = Maruku
+          else
+            raise "Requested unsupported Markdown parser: #{parser}."
+          end
+        end
+        
+        def load_custom_helpers
+          begin
+            require File.join(templates_directory, "helpers")
+          rescue LoadError => e
+            return nil
+          end
+          self.class.__send__(:include, Helpers::BaseHelper)
+          Page.__send__(:include, Helpers::BaseHelper)
+          Helpers.constants.map(&Helpers.method(:const_get)).each(&DocPage.method(:include))
+        end
+        
+        # Generates the website to the specified directory.
+        def render(output)
+          @depth = 0
+          path = File.expand_path(output)
+          FileUtils.mkdir_p(path)
+          Dir.chdir(path) do
+          
+            render_index
+            copy_assets
+            copy_custom_assets
+            
+            render_children(root)
+            if root.sections?
+              root.sections.each do |section|
+                @depth = 0
+                render_template('section', { :doc_instance => section })
+              end
+            end
+
+            dest = File.join("javascripts", "pdoc", "item_index.js")
+            DocPage.new("item_index.js", false, variables).render_to_file(dest)
+          end
+        end
+        
+        def render_index
+          vars = variables.merge(:index_page_content => index_page_content, :home => true)
+          DocPage.new('index', 'layout', vars).render_to_file('index.html')
+        end
+        
+        def render_template(template, var = {})
+          @depth += 1
+          doc = var[:doc_instance]
+          dest = doc.url(File::SEPARATOR)
+          puts "        Rendering #{dest}..."
+          FileUtils.mkdir_p(dest)
+          DocPage.new(template, variables.merge(var)).render_to_file(File.join(dest, 'index.html'))
+          render_json("#{dest}.json", doc) if json_api?
+          render_children(doc)
+          @depth -= 1
+        end
+        
+        def render_json(dest, obj)
+          open(dest, 'w') { |file| file << obj.to_json }
+        end
+        
+        def render_children(obj)
+          [:namespaces, :classes, :mixins].each do |prop|
+            obj.send(prop).each(&method(:render_node)) if obj.respond_to?(prop)
+          end
+          
+          obj.utilities.each(&method(:render_leaf)) if obj.respond_to?(:utilities)
+          render_leaf(obj.constructor) if obj.respond_to?(:constructor) && obj.constructor
+          
+          [:instance_methods, :instance_properties, :class_methods, :class_properties, :constants].each do |prop|
+            obj.send(prop).each(&method(:render_leaf)) if obj.respond_to?(prop)
+          end
+        end
+        
+        # Copies the content of the assets folder to the generated website's
+        # root directory.
+        def copy_assets
+          FileUtils.cp_r(Dir.glob(File.join(templates_directory, "assets", "**")), '.')
+        end
+        
+        def copy_custom_assets
+          if custom_assets
+            FileUtils.cp_r(Dir.glob(File.join(custom_assets, "**")), ".")
+          end
+        end
+        
+        def render_leaf(object)
+          is_proto_prop = is_proto_prop?(object)
+          @depth += 1 if is_proto_prop
+          render_template('leaf', { :doc_instance => object })
+          @depth -= 1 if is_proto_prop
+        end
+        
+        def render_node(object)          
+          render_template('node', { :doc_instance => object })
+        end
+        
+        private
+          def variables
+            {
+              :root => root,
+              :depth => @depth,
+              :templates_directory => templates_directory,
+              :name => @options[:name],
+              :short_name => @options[:short_name] || @options[:name],
+              :home_url => @options[:home_url],
+              :version => @options[:version],
+              :footer => footer,
+              :index_header => index_header,
+              :header => header,
+              :timestamp => timestamp
+            }
+          end
+
+          def header
+            @header ||= @options[:header] ? htmlize(@options[:header]) : ''
+          end
+          
+          def index_header
+            @index_header ||= @options[:index_header] ? htmlize(@options[:index_header]) : ''
+          end
+          
+          def footer
+            @footer ||= @options[:footer] ? htmlize(@options[:footer]) : ''
+          end
+          
+          def timestamp
+            @timestamp ||= @options[:timestamp] == false ? nil : Time.now.utc
+          end
+          
+          def json_api?
+            !!options[:json_api]
+          end
+          
+          def is_proto_prop?(object)
+            object.is_a?(Models::InstanceMethod) ||
+              object.is_a?(Models::InstanceProperty)
+          end
+          
+          def index_page_content
+            @index_page ? htmlize(File.read(@index_page)) : nil
+          end
+      end
+    end
+  end
+end

data/lib/pdoc/generators/json.rb

@@ -0,0 +1,15 @@
+require 'json'
+module PDoc
+  module Generators
+    class JSON < AbstractGenerator
+      def render(output)
+        open(output, "w+") do |file|
+          json = root.registry.map do |k, obj|
+            "#{k.inspect}: #{obj.to_json}"
+          end.join(",\n  ")
+          file << "{\n  #{json}\n}"
+        end
+      end
+    end
+  end
+end

data/lib/pdoc/generators/pythonesque.rb

@@ -0,0 +1,105 @@
+module PDoc
+  module Generators
+    class Pythonesque < AbstractGenerator
+      def render(output)
+        open(output, "w+") do |file|
+          file << render_to_str
+        end
+      end
+      
+      def render_to_str
+        selected_objects.map do |k, obj|
+          js_name = to_js_name(obj)
+          desc = Description.new(obj).to_escaped_str
+          " #{js_name}.__doc__ = '#{desc}';"
+        end.join("\n")
+      end
+      
+      def to_js_name(obj)
+        if obj.is_a?(Models::InstanceMethod)
+          obj.full_name.sub('#', '.prototype.')
+        else
+          obj.full_name
+        end
+      end
+      
+      def selected_objects
+        root.registry.select do |k, v|
+          (v.is_a?(Models::InstanceMethod) ||
+          v.is_a?(Models::ClassMethod) ||
+          v.is_a?(Models::Mixin) ||
+          v.is_a?(Models::Class) ||
+          v.is_a?(Models::Namespace) ||
+          v.is_a?(Models::Utility)) && !v.alias?
+        end
+      end
+      
+      class Description
+        JS_ESCAPE_MAP = {
+          '\\'    => '\\\\',
+          '</'    => '<\/',
+          "\r\n"  => '\n',
+          "\n"    => '\n',
+          "\r"    => '\n',
+          '"'     => '\\"',
+          "'"     => "\\'"
+        }
+        
+        attr_reader :obj
+        def initialize(obj)
+          @obj = obj
+        end
+        
+        def to_str
+          return "#{obj.full_name} has been deprecated." if obj.deprecated?
+          results = []
+          results << sig
+          results << args if obj.respond_to?(:arguments) && obj.arguments?
+          results << desc
+          results << aliases if obj.aliases?
+          if obj.respond_to?(:constructor) && obj.constructor
+            results << "\nWhen called as a constructor:\n"
+            results << Description.new(obj.constructor).to_str
+          end
+          results.join("\n")
+        end
+        
+        def to_escaped_str
+          escape(to_str)
+        end
+        
+        private
+          def escape(str)
+            str.gsub(/(\\|<\/|\r\n|[\n\r"'])/) {
+              JS_ESCAPE_MAP[$1]
+            }
+          end
+        
+          def sig
+            if obj.signatures?
+              obj.signatures.map do |s|
+                s.return_value ? "#{s.name} -> #{s.return_value}" : s.name
+              end.join("\n")
+            else
+              obj.full_name
+            end
+          end
+        
+          def aliases
+            aliases = obj.aliases.map { |a| a.full_name }.join(', ')
+            "Aliased as: #{aliases}."
+          end
+        
+          def args
+            obj.arguments.map do |a|
+               "  - #{a.name} (#{a.types.join(' | ')}): #{a.description.chomp}"
+            end.join("\n")
+          end
+        
+          def desc
+            obj.short_description ? obj.short_description : ''
+          end
+      end
+    end
+  end
+end