RubyGems - sdoc_local_editor - Versions diffs - 0.3.17 - Mend

sdoc_local_editor 0.3.17

Files changed (59) hide show

data/.gitignore +3 -0
data/.rake_tasks~ +20 -0
data/LICENSE +110 -0
data/README.rdoc +37 -0
data/Rakefile +12 -0
data/bin/sdoc_local_editor +27 -0
data/bin/sdoc_local_editor_merge +24 -0
data/lib/rdoc/discover.rb +5 -0
data/lib/rdoc/generator/template/merge/index.rhtml +14 -0
data/lib/rdoc/generator/template/rails/_context.rhtml +210 -0
data/lib/rdoc/generator/template/rails/_head.rhtml +7 -0
data/lib/rdoc/generator/template/rails/class.rhtml +39 -0
data/lib/rdoc/generator/template/rails/file.rhtml +37 -0
data/lib/rdoc/generator/template/rails/index.rhtml +13 -0
data/lib/rdoc/generator/template/rails/resources/apple-touch-icon.png +0 -0
data/lib/rdoc/generator/template/rails/resources/css/github.css +129 -0
data/lib/rdoc/generator/template/rails/resources/css/main.css +346 -0
data/lib/rdoc/generator/template/rails/resources/css/panel.css +389 -0
data/lib/rdoc/generator/template/rails/resources/css/reset.css +48 -0
data/lib/rdoc/generator/template/rails/resources/favicon.ico +0 -0
data/lib/rdoc/generator/template/rails/resources/i/arrows.png +0 -0
data/lib/rdoc/generator/template/rails/resources/i/results_bg.png +0 -0
data/lib/rdoc/generator/template/rails/resources/i/tree_bg.png +0 -0
data/lib/rdoc/generator/template/rails/resources/js/highlight.pack.js +1 -0
data/lib/rdoc/generator/template/rails/resources/js/jquery-1.3.2.min.js +19 -0
data/lib/rdoc/generator/template/rails/resources/js/jquery-effect.js +593 -0
data/lib/rdoc/generator/template/rails/resources/js/main.js +20 -0
data/lib/rdoc/generator/template/rails/resources/js/searchdoc.js +441 -0
data/lib/rdoc/generator/template/rails/resources/panel/index.html +73 -0
data/lib/rdoc/generator/template/rails/se_index.rhtml +8 -0
data/lib/rdoc/generator/template/sdoc/_context.rhtml +221 -0
data/lib/rdoc/generator/template/sdoc/_head.rhtml +7 -0
data/lib/rdoc/generator/template/sdoc/class.rhtml +39 -0
data/lib/rdoc/generator/template/sdoc/file.rhtml +29 -0
data/lib/rdoc/generator/template/sdoc/index.rhtml +13 -0
data/lib/rdoc/generator/template/sdoc/resources/apple-touch-icon.png +0 -0
data/lib/rdoc/generator/template/sdoc/resources/css/github.css +129 -0
data/lib/rdoc/generator/template/sdoc/resources/css/main.css +333 -0
data/lib/rdoc/generator/template/sdoc/resources/css/panel.css +384 -0
data/lib/rdoc/generator/template/sdoc/resources/css/reset.css +48 -0
data/lib/rdoc/generator/template/sdoc/resources/favicon.ico +0 -0
data/lib/rdoc/generator/template/sdoc/resources/i/arrows.png +0 -0
data/lib/rdoc/generator/template/sdoc/resources/i/results_bg.png +0 -0
data/lib/rdoc/generator/template/sdoc/resources/i/tree_bg.png +0 -0
data/lib/rdoc/generator/template/sdoc/resources/js/highlight.pack.js +1 -0
data/lib/rdoc/generator/template/sdoc/resources/js/jquery-1.3.2.min.js +19 -0
data/lib/rdoc/generator/template/sdoc/resources/js/jquery-effect.js +593 -0
data/lib/rdoc/generator/template/sdoc/resources/js/main.js +24 -0
data/lib/rdoc/generator/template/sdoc/resources/js/searchdoc.js +442 -0
data/lib/rdoc/generator/template/sdoc/resources/panel/index.html +73 -0
data/lib/rdoc/generator/template/sdoc/se_index.rhtml +8 -0
data/lib/sdoc_local_editor.rb +9 -0
data/lib/sdoc_local_editor/generator.rb +418 -0
data/lib/sdoc_local_editor/github.rb +61 -0
data/lib/sdoc_local_editor/helpers.rb +26 -0
data/lib/sdoc_local_editor/merge.rb +223 -0
data/lib/sdoc_local_editor/templatable.rb +60 -0
data/sdoc_local_editor.gemspec +31 -0
metadata +139 -0

data/lib/rdoc/generator/template/sdoc/resources/panel/index.html ADDED

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+	<title>search index</title>
+	<link rel="stylesheet" href="../css/reset.css" type="text/css" media="screen" charset="utf-8" />
+	<link rel="stylesheet" href="../css/panel.css" type="text/css" media="screen" charset="utf-8" />
+	<script src="../js/search_index.js" type="text/javascript" charset="utf-8"></script>
+	<script src="../js/searcher.js" type="text/javascript" charset="utf-8"></script>
+	<script src="tree.js" type="text/javascript" charset="utf-8"></script>
+	<script src="../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
+	<script src="../js/searchdoc.js" type="text/javascript" charset="utf-8"></script>
+	<script type="text/javascript" charset="utf-8">
+    function placeholder() {
+        if ($('<input type="text">')[0].placeholder !== undefined) return;
+        $('#search-label').click(function() {
+            $('#search').focus();
+            $('#search-label').hide();
+        });
+        $('#search').focus(function() {
+            $('#search-label').hide();
+        });
+        $('#search').blur(function() {
+            this.value == '' && $('#search-label').show()
+        });
+        $('#search')[0].value == '' && $('#search-label').show();
+    }
+    $(function() {
+        placeholder();
+        $('#links').hide();
+        var panel = new Searchdoc.Panel($('#panel'), search_data, tree, top.frames[1]);
+        $('#search').focus();
+        var s = window.parent.location.search.match(/\?q=([^&]+)/);
+        if (s) {
+            s = decodeURIComponent(s[1]).replace(/\+/g, ' ');
+            if (s.length > 0)
+            {
+                $('#search').val(s);
+                panel.search(s, true);
+            }
+        }
+    })
+	</script>
+</head>
+<body>
+    <div class="panel panel_tree" id="panel">
+        <div class="header">
+            <div>
+                <label for="search" id="search-label" style="display: none">Search</label>
+                <table>
+                <tr><td>
+                    <input type="Search" placeholder="Search" autosave="searchdoc" results="10" id="search" autocomplete="off"/>
+                </td></tr>
+            </table></div>
+        </div>
+        <div class="tree">
+            <ul>
+            </ul>
+        </div>
+        <div class="result">
+            <ul>
+            </ul>
+        </div>
+    </div>
+    <a href="links.html" id="links">index</a>
+</body>
+</html>

data/lib/rdoc/generator/template/sdoc/se_index.rhtml ADDED

@@ -0,0 +1,8 @@
+<html>
+    <head>File index</head>
+    <body>
+    <% @files.each do |file| %>
+      <a href="../<%= file.path %>"><%= file.relative_name %></a>
+    <% end %>
+    </body>
+</html>

data/lib/sdoc_local_editor.rb ADDED

@@ -0,0 +1,9 @@
+$:.unshift File.dirname(__FILE__)
+SOURCE_DIR = Dir.pwd
+require "rubygems"
+gem 'rdoc', '~> 3'
+module SDoc end
+require 'sdoc_local_editor/generator'

data/lib/sdoc_local_editor/generator.rb ADDED

@@ -0,0 +1,418 @@
+require 'rubygems'
+require 'erb'
+require 'pathname'
+require 'fileutils'
+if Gem::Specification.respond_to?(:find_by_name) ? Gem::Specification::find_by_name("json") : Gem.available?("json")
+  gem "json", ">= 1.1.3"
+else
+  gem "json_pure", ">= 1.1.3"
+end
+require 'json'
+require 'sdoc_local_editor/github'
+require 'sdoc_local_editor/templatable'
+require 'sdoc_local_editor/helpers'
+require 'rdoc'
+class RDoc::ClassModule
+  def with_documentation?
+    document_self_or_methods || classes_and_modules.any?{ |c| c.with_documentation? }
+  end
+end
+class RDoc::Options
+  attr_accessor :github, :se_index, :local_editor
+end
+class RDoc::AnyMethod
+  TITLE_AFTER = %w(def class module)
+  ##
+  # Turns the method's token stream into HTML.
+  #
+  # Prepends line numbers if +add_line_numbers+ is true.
+  def sdoc_markup_code
+    return '' unless @token_stream
+    src = ""
+    starting_title = false
+    @token_stream.each do |t|
+      next unless t
+      style = case t
+              when RDoc::RubyToken::TkFLOAT    then 'ruby-number'
+              when RDoc::RubyToken::TkINTEGER  then 'ruby-number'
+              when RDoc::RubyToken::TkCONSTANT then 'ruby-constant'
+              when RDoc::RubyToken::TkKW       then 'ruby-keyword'
+              when RDoc::RubyToken::TkIVAR     then 'ruby-ivar'
+              when RDoc::RubyToken::TkOp       then 'ruby-operator'
+              when RDoc::RubyToken::TkId       then 'ruby-identifier'
+              when RDoc::RubyToken::TkNode     then 'ruby-node'
+              when RDoc::RubyToken::TkCOMMENT  then 'ruby-comment'
+              when RDoc::RubyToken::TkREGEXP   then 'ruby-regexp'
+              when RDoc::RubyToken::TkSTRING   then 'ruby-string'
+              when RDoc::RubyToken::TkVal      then 'ruby-value'
+              end
+      if RDoc::RubyToken::TkId === t && starting_title
+        starting_title = false
+        style = 'ruby-keyword ruby-title'
+      end
+      if RDoc::RubyToken::TkKW === t && TITLE_AFTER.include?(t.text)
+        starting_title = true
+      end
+      text = CGI.escapeHTML t.text
+      if style then
+        src << "<span class=\"#{style}\">#{text}</span>"
+      else
+        src << text
+      end
+    end
+    # dedent the source
+    indent = src.length
+    lines = src.lines.to_a
+    lines.shift if src =~ /\A.*#\ *File/i # remove '# File' comment
+    lines.each do |line|
+      if line =~ /^ *(?=\S)/
+        n = $&.length
+        indent = n if n < indent
+        break if n == 0
+      end
+    end
+    src.gsub!(/^#{' ' * indent}/, '') if indent > 0
+    add_line_numbers(src) if self.class.add_line_numbers
+    src
+  end
+end
+class RDoc::Generator::SDoc
+  RDoc::RDoc.add_generator self
+  DESCRIPTION = 'Searchable HTML documentation'
+  include ERB::Util
+  include SDoc::GitHub
+  include SDoc::Templatable
+  include SDoc::Helpers
+  GENERATOR_DIRS = [File.join('sdoc_local_editor', 'generator')]
+  TREE_FILE = File.join 'panel', 'tree.js'
+  SEARCH_INDEX_FILE = File.join 'js', 'search_index.js'
+  FILE_DIR = 'files'
+  CLASS_DIR = 'classes'
+  RESOURCES_DIR = File.join('resources', '.')
+  attr_reader :base_dir
+  attr_reader :options
+  def self.setup_options(options)
+    @github = false
+    options.se_index = true
+    options.local_editor = true
+    opt = options.option_parser
+    opt.separator nil
+    opt.separator "SDoc generator options:"
+    opt.separator nil
+    opt.on("--github", "-g",
+           "Generate links to github.") do |value|
+      options.github = true
+    end
+    opt.separator nil
+    opt.on("--no-se-index", "-ns",
+           "Do not generated index file for search engines.",
+           "SDoc uses javascript to refrence individual documentation pages.",
+           "Search engine crawlers are not smart enough to find all the",
+           "referenced pages.",
+           "To help them SDoc generates a static file with links to every",
+           "documentation page. This file is not shown to the user."
+           ) do |value|
+      options.se_index = false
+    end
+    opt.separator nil
+    opt.on("--local-editor", "-L",
+           "Generate links to open file in local editor.",
+           "The server serving this documentation should respond to",
+           "a POST request to /open_editor/. The request will contain",
+           "the following query parameters:",
+           "  * file  -- the file path, relative to your code directory",
+           "  * line  -- the line number in the file."
+          ) do |value|
+      options.local_editor = true
+    end
+    opt.separator nil
+  end
+  def initialize(options)
+    @options = options
+    if @options.respond_to?('diagram=')
+      @options.diagram = false
+    end
+    @github_url_cache = {}
+    @template_dir = Pathname.new(options.template_dir)
+    @base_dir = Pathname.pwd.expand_path
+    @json_index = RDoc::Generator::JsonIndex.new self, options
+  end
+  def generate(top_levels)
+    @outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir)
+    @files = top_levels.sort
+    @classes = RDoc::TopLevel.all_classes_and_modules.sort
+    # Now actually write the output
+    copy_resources
+    generate_class_tree
+    @json_index.generate top_levels
+    generate_file_files
+    generate_class_files
+    generate_index_file
+    generate_se_index if @options.se_index
+  end
+  def class_dir
+    CLASS_DIR
+  end
+  def file_dir
+    FILE_DIR
+  end
+  protected
+  ### Output progress information if debugging is enabled
+  def debug_msg( *msg )
+    return unless $DEBUG_RDOC
+    $stderr.puts( *msg )
+  end
+  ### Create class tree structure and write it as json
+  def generate_class_tree
+    debug_msg "Generating class tree"
+    topclasses = @classes.select {|klass| !(RDoc::ClassModule === klass.parent) }
+    tree = generate_file_tree + generate_class_tree_level(topclasses)
+    debug_msg "  writing class tree to %s" % TREE_FILE
+    File.open(TREE_FILE, "w", 0644) do |f|
+      f.write('var tree = '); f.write(tree.to_json(:max_nesting => 0))
+    end unless $dryrun
+  end
+  ### Recursivly build class tree structure
+  def generate_class_tree_level(classes, visited = {})
+    tree = []
+    classes.select do |klass|
+      !visited[klass] && klass.with_documentation?
+    end.sort.each do |klass|
+      visited[klass] = true
+      item = [
+        klass.name,
+        klass.document_self_or_methods ? klass.path : '',
+        klass.module? ? '' : (klass.superclass ? " < #{String === klass.superclass ? klass.superclass : klass.superclass.full_name}" : ''),
+        generate_class_tree_level(klass.classes_and_modules, visited)
+      ]
+      tree << item
+    end
+    tree
+  end
+  ### Add files to search +index+ array
+  def add_file_search_index(index)
+    debug_msg "  generating file search index"
+    @files.select { |file|
+      file.document_self
+    }.sort.each do |file|
+      debug_msg "    #{file.path}"
+      index[:searchIndex].push( search_string(file.name) )
+      index[:longSearchIndex].push( search_string(file.path) )
+      index[:info].push([
+        file.name,
+        file.path,
+        file.path,
+        '',
+        snippet(file.comment),
+        TYPE_FILE
+      ])
+    end
+  end
+  ### Add classes to search +index+ array
+  def add_class_search_index(index)
+    debug_msg "  generating class search index"
+    @classes.uniq.select { |klass|
+      klass.document_self_or_methods
+    }.sort.each do |klass|
+      modulename = klass.module? ? '' : (klass.superclass ? (String === klass.superclass ? klass.superclass : klass.superclass.full_name) : '')
+      debug_msg "    #{klass.parent.full_name}::#{klass.name}"
+      index[:searchIndex].push( search_string(klass.name) )
+      index[:longSearchIndex].push( search_string(klass.parent.full_name) )
+      files = klass.in_files.map{ |file| file.absolute_name }
+      index[:info].push([
+        klass.name,
+        files.include?(klass.parent.full_name) ? files.first : klass.parent.full_name,
+        klass.path,
+        modulename ? " < #{modulename}" : '',
+        snippet(klass.comment),
+        TYPE_CLASS
+      ])
+    end
+  end
+  ### Add methods to search +index+ array
+  def add_method_search_index(index)
+    debug_msg "  generating method search index"
+    list = @classes.uniq.map do |klass|
+      klass.method_list
+    end.flatten.sort do |a, b|
+      a.name == b.name ?
+        a.parent.full_name <=> b.parent.full_name :
+        a.name <=> b.name
+    end.select do |method|
+      method.document_self
+    end.find_all do |m|
+      m.visibility == :public || m.visibility == :protected ||
+      m.force_documentation
+    end
+    list.each do |method|
+      debug_msg "    #{method.full_name}"
+      index[:searchIndex].push( search_string(method.name) + '()' )
+      index[:longSearchIndex].push( search_string(method.parent.full_name) )
+      index[:info].push([
+        method.name,
+        method.parent.full_name,
+        method.path,
+        method.params,
+        snippet(method.comment),
+        TYPE_METHOD
+      ])
+    end
+  end
+  ### Generate a documentation file for each class
+  def generate_class_files
+    debug_msg "Generating class documentation in #@outputdir"
+    templatefile = @template_dir + 'class.rhtml'
+    @classes.each do |klass|
+      debug_msg "  working on %s (%s)" % [ klass.full_name, klass.path ]
+      outfile     = @outputdir + klass.path
+      rel_prefix  = @outputdir.relative_path_from( outfile.dirname )
+      debug_msg "  rendering #{outfile}"
+      self.render_template( templatefile, binding(), outfile )
+    end
+  end
+  ### Generate a documentation file for each file
+  def generate_file_files
+    debug_msg "Generating file documentation in #@outputdir"
+    templatefile = @template_dir + 'file.rhtml'
+    @files.each do |file|
+      outfile     = @outputdir + file.path
+      debug_msg "  working on %s (%s)" % [ file.full_name, outfile ]
+      rel_prefix  = @outputdir.relative_path_from( outfile.dirname )
+      debug_msg "  rendering #{outfile}"
+      self.render_template( templatefile, binding(), outfile )
+    end
+  end
+  ### Determines index path based on @options.main_page (or lack thereof)
+  def index_path
+    # Break early to avoid a big if block when no main page is specified
+    default = @files.first.path
+    return default unless @options.main_page
+    # Transform class name to file path
+    if @options.main_page.include?("::")
+      slashed = @options.main_page.sub(/^::/, "").gsub("::", "/")
+      "%s/%s.html" % [ class_dir, slashed ]
+    elsif file = @files.find { |f| f.full_name == @options.main_page }
+      file.path
+    else
+      default
+    end
+  end
+  ### Create index.html with frameset
+  def generate_index_file
+    debug_msg "Generating index file in #@outputdir"
+    templatefile = @template_dir + 'index.rhtml'
+    outfile      = @outputdir + 'index.html'
+    self.render_template( templatefile, binding(), outfile )
+  end
+  ### Generate file with links for the search engine
+  def generate_se_index
+    debug_msg "Generating search engine index in #@outputdir"
+    templatefile = @template_dir + 'se_index.rhtml'
+    outfile      = @outputdir + 'panel/links.html'
+    self.render_template( templatefile, binding(), outfile )
+  end
+  ### Copy all the resource files to output dir
+  def copy_resources
+    resoureces_path = @template_dir + RESOURCES_DIR
+    debug_msg "Copying #{resoureces_path}/** to #{@outputdir}/**"
+    FileUtils.cp_r resoureces_path.to_s, @outputdir.to_s, :preserve => true unless $dryrun
+  end
+  class FilesTree
+    attr_reader :children
+    def add(path, url)
+      path = path.split(File::SEPARATOR) unless Array === path
+      @children ||= {}
+      if path.length == 1
+        @children[path.first] = url
+      else
+        @children[path.first] ||= FilesTree.new
+        @children[path.first].add(path[1, path.length], url)
+      end
+    end
+  end
+  def generate_file_tree
+    if @files.length > 1
+      @files_tree = FilesTree.new
+      @files.each do |file|
+        @files_tree.add(file.relative_name, file.path)
+      end
+      [['', '', 'files', generate_file_tree_level(@files_tree)]]
+    else
+      []
+    end
+  end
+  def generate_file_tree_level(tree)
+    tree.children.keys.sort.map do |name|
+      child = tree.children[name]
+      if String === child
+        [name, child, '', []]
+      else
+        ['', '', name, generate_file_tree_level(child)]
+      end
+    end
+  end
+end