rdoc 3.1 → 6.3.3

data/lib/rdoc/generator/json_index.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+require 'json'
+begin
+  require 'zlib'
+rescue LoadError
+end
+
+##
+# The JsonIndex generator is designed to complement an HTML generator and
+# produces a JSON search index.  This generator is derived from sdoc by
+# Vladimir Kolesnikov and contains verbatim code written by him.
+#
+# This generator is designed to be used with a regular HTML generator:
+#
+#   class RDoc::Generator::Darkfish
+#     def initialize options
+#       # ...
+#       @base_dir = Pathname.pwd.expand_path
+#
+#       @json_index = RDoc::Generator::JsonIndex.new self, options
+#     end
+#
+#     def generate
+#       # ...
+#       @json_index.generate
+#     end
+#   end
+#
+# == Index Format
+#
+# The index is output as a JSON file assigned to the global variable
+# +search_data+.  The structure is:
+#
+#   var search_data = {
+#     "index": {
+#       "searchIndex":
+#         ["a", "b", ...],
+#       "longSearchIndex":
+#         ["a", "a::b", ...],
+#       "info": [
+#         ["A", "A", "A.html", "", ""],
+#         ["B", "A::B", "A::B.html", "", ""],
+#         ...
+#       ]
+#     }
+#   }
+#
+# The same item is described across the +searchIndex+, +longSearchIndex+ and
+# +info+ fields.  The +searchIndex+ field contains the item's short name, the
+# +longSearchIndex+ field contains the full_name (when appropriate) and the
+# +info+ field contains the item's name, full_name, path, parameters and a
+# snippet of the item's comment.
+#
+# == LICENSE
+#
+# Copyright (c) 2009 Vladimir Kolesnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+class RDoc::Generator::JsonIndex
+
+  include RDoc::Text
+
+  ##
+  # Where the search index lives in the generated output
+
+  SEARCH_INDEX_FILE = File.join 'js', 'search_index.js'
+
+  attr_reader :index # :nodoc:
+
+  ##
+  # Creates a new generator.  +parent_generator+ is used to determine the
+  # class_dir and file_dir of links in the output index.
+  #
+  # +options+ are the same options passed to the parent generator.
+
+  def initialize parent_generator, options
+    @parent_generator = parent_generator
+    @store            = parent_generator.store
+    @options          = options
+
+    @template_dir = File.expand_path '../template/json_index', __FILE__
+    @base_dir = @parent_generator.base_dir
+
+    @classes = nil
+    @files   = nil
+    @index   = nil
+  end
+
+  ##
+  # Builds the JSON index as a Hash.
+
+  def build_index
+    reset @store.all_files.sort, @store.all_classes_and_modules.sort
+
+    index_classes
+    index_methods
+    index_pages
+
+    { :index => @index }
+  end
+
+  ##
+  # Output progress information if debugging is enabled
+
+  def debug_msg *msg
+    return unless $DEBUG_RDOC
+    $stderr.puts(*msg)
+  end
+
+  ##
+  # Writes the JSON index to disk
+
+  def generate
+    debug_msg "Generating JSON index"
+
+    debug_msg "  writing search index to %s" % SEARCH_INDEX_FILE
+    data = build_index
+
+    return if @options.dry_run
+
+    out_dir = @base_dir + @options.op_dir
+    index_file = out_dir + SEARCH_INDEX_FILE
+
+    FileUtils.mkdir_p index_file.dirname, :verbose => $DEBUG_RDOC
+
+    index_file.open 'w', 0644 do |io|
+      io.set_encoding Encoding::UTF_8
+      io.write 'var search_data = '
+
+      JSON.dump data, io, 0
+    end
+    unless ENV['SOURCE_DATE_EPOCH'].nil?
+      index_file.utime index_file.atime, Time.at(ENV['SOURCE_DATE_EPOCH'].to_i).gmtime
+    end
+
+    Dir.chdir @template_dir do
+      Dir['**/*.js'].each do |source|
+        dest = File.join out_dir, source
+
+        FileUtils.install source, dest, :mode => 0644, :preserve => true, :verbose => $DEBUG_RDOC
+      end
+    end
+  end
+
+  ##
+  # Compress the search_index.js file using gzip
+
+  def generate_gzipped
+    return if @options.dry_run or not defined?(Zlib)
+
+    debug_msg "Compressing generated JSON index"
+    out_dir = @base_dir + @options.op_dir
+
+    search_index_file = out_dir + SEARCH_INDEX_FILE
+    outfile           = out_dir + "#{search_index_file}.gz"
+
+    debug_msg "Reading the JSON index file from %s" % search_index_file
+    search_index = search_index_file.read(mode: 'r:utf-8')
+
+    debug_msg "Writing gzipped search index to %s" % outfile
+
+    Zlib::GzipWriter.open(outfile) do |gz|
+      gz.mtime = File.mtime(search_index_file)
+      gz.orig_name = search_index_file.basename.to_s
+      gz.write search_index
+      gz.close
+    end
+
+    # GZip the rest of the js files
+    Dir.chdir @template_dir do
+      Dir['**/*.js'].each do |source|
+        dest = out_dir + source
+        outfile = out_dir + "#{dest}.gz"
+
+        debug_msg "Reading the original js file from %s" % dest
+        data = dest.read
+
+        debug_msg "Writing gzipped file to %s" % outfile
+
+        Zlib::GzipWriter.open(outfile) do |gz|
+          gz.mtime = File.mtime(dest)
+          gz.orig_name = dest.basename.to_s
+          gz.write data
+          gz.close
+        end
+      end
+    end
+  end
+
+  ##
+  # Adds classes and modules to the index
+
+  def index_classes
+    debug_msg "  generating class search index"
+
+    documented = @classes.uniq.select do |klass|
+      klass.document_self_or_methods
+    end
+
+    documented.each do |klass|
+      debug_msg "    #{klass.full_name}"
+      record = klass.search_record
+      @index[:searchIndex]     << search_string(record.shift)
+      @index[:longSearchIndex] << search_string(record.shift)
+      @index[:info]            << record
+    end
+  end
+
+  ##
+  # Adds methods to the index
+
+  def index_methods
+    debug_msg "  generating method search index"
+
+    list = @classes.uniq.map do |klass|
+      klass.method_list
+    end.flatten.sort_by do |method|
+      [method.name, method.parent.full_name]
+    end
+
+    list.each do |method|
+      debug_msg "    #{method.full_name}"
+      record = method.search_record
+      @index[:searchIndex]     << "#{search_string record.shift}()"
+      @index[:longSearchIndex] << "#{search_string record.shift}()"
+      @index[:info]            << record
+    end
+  end
+
+  ##
+  # Adds pages to the index
+
+  def index_pages
+    debug_msg "  generating pages search index"
+
+    pages = @files.select do |file|
+      file.text?
+    end
+
+    pages.each do |page|
+      debug_msg "    #{page.page_name}"
+      record = page.search_record
+      @index[:searchIndex]     << search_string(record.shift)
+      @index[:longSearchIndex] << ''
+      record.shift
+      @index[:info]            << record
+    end
+  end
+
+  ##
+  # The directory classes are written to
+
+  def class_dir
+    @parent_generator.class_dir
+  end
+
+  ##
+  # The directory files are written to
+
+  def file_dir
+    @parent_generator.file_dir
+  end
+
+  def reset files, classes # :nodoc:
+    @files   = files
+    @classes = classes
+
+    @index = {
+      :searchIndex => [],
+      :longSearchIndex => [],
+      :info => []
+    }
+  end
+
+  ##
+  # Removes whitespace and downcases +string+
+
+  def search_string string
+    string.downcase.gsub(/\s/, '')
+  end
+
+end

data/lib/rdoc/generator/markup.rb

@@ -1,10 +1,9 @@
-require 'rdoc/text'
-require 'rdoc/code_objects'
-require 'rdoc/generator'
-require 'rdoc/markup/to_html_crossref'
-
+# frozen_string_literal: true
 ##
 # Handle common RDoc::Markup tasks for various CodeObjects
+#
+# This module is loaded by generators.  It allows RDoc's CodeObject tree to
+# avoid loading generator code to improve startup time for +ri+.
 
 module RDoc::Generator::Markup
 
@@ -35,16 +34,18 @@ module RDoc::Generator::Markup
   def formatter
     return @formatter if defined? @formatter
 
-    show_hash = RDoc::RDoc.current.options.show_hash
-    hyperlink_all = RDoc::RDoc.current.options.hyperlink_all
+    options = @store.rdoc.options
     this = RDoc::Context === self ? self : @parent
-    @formatter = RDoc::Markup::ToHtmlCrossref.new this.path, this, show_hash, hyperlink_all
+
+    @formatter = RDoc::Markup::ToHtmlCrossref.new options, this.path, this
+    @formatter.code_object = self
+    @formatter
   end
 
   ##
   # Build a webcvs URL starting for the given +url+ with +full_path+ appended
   # as the destination path.  If +url+ contains '%s' +full_path+ will be
-  # sprintf'd into +url+ instead.
+  # will replace the %s using sprintf on the +url+.
 
   def cvs_url(url, full_path)
     if /%s/ =~ url then
@@ -56,35 +57,13 @@ module RDoc::Generator::Markup
 
 end
 
-class RDoc::AnyMethod
-
-  ##
-  # Maps RDoc::RubyToken classes to CSS class names
-
-  STYLE_MAP = {
-    RDoc::RubyToken::TkCONSTANT => 'ruby-constant',
-    RDoc::RubyToken::TkKW       => 'ruby-keyword',
-    RDoc::RubyToken::TkIVAR     => 'ruby-ivar',
-    RDoc::RubyToken::TkOp       => 'ruby-operator',
-    RDoc::RubyToken::TkId       => 'ruby-identifier',
-    RDoc::RubyToken::TkNode     => 'ruby-node',
-    RDoc::RubyToken::TkCOMMENT  => 'ruby-comment',
-    RDoc::RubyToken::TkREGEXP   => 'ruby-regexp',
-    RDoc::RubyToken::TkSTRING   => 'ruby-string',
-    RDoc::RubyToken::TkVal      => 'ruby-value',
-  }
+class RDoc::CodeObject
 
   include RDoc::Generator::Markup
 
-  @add_line_numbers = false
-
-  class << self
-    ##
-    # Allows controlling whether <tt>#markup_code</tt> adds line numbers to
-    # the source code.
+end
 
-    attr_accessor :add_line_numbers
-  end
+class RDoc::MethodAttr
 
   ##
   # Prepend +src+ with line numbers.  Relies on the first line of a source
@@ -92,7 +71,8 @@ class RDoc::AnyMethod
   #
   #   # File xxxxx, line dddd
   #
-  # If it has, line numbers are added an ', line dddd' is removed.
+  # If it has this comment then line numbers are added to +src+ and the <tt>,
+  # line dddd</tt> portion of the comment is removed.
 
   def add_line_numbers(src)
     return unless src.sub!(/\A(.*)(, line (\d+))/, '\1')
@@ -116,26 +96,12 @@ class RDoc::AnyMethod
   ##
   # Turns the method's token stream into HTML.
   #
-  # Prepends line numbers if +add_line_numbers+ is true.
+  # Prepends line numbers if +options.line_numbers+ is true.
 
   def markup_code
     return '' unless @token_stream
 
-    src = ""
-
-    @token_stream.each do |t|
-      next unless t
-
-      style = STYLE_MAP[t.class]
-
-      text = CGI.escapeHTML t.text
-
-      if style then
-        src << "<span class=\"#{style}\">#{text}</span>"
-      else
-        src << text
-      end
-    end
+    src = RDoc::TokenStream.to_html @token_stream
 
     # dedent the source
     indent = src.length
@@ -150,34 +116,21 @@ class RDoc::AnyMethod
     end
     src.gsub!(/^#{' ' * indent}/, '') if indent > 0
 
-    add_line_numbers(src) if self.class.add_line_numbers
+    add_line_numbers(src) if options.line_numbers
 
     src
   end
 
 end
 
-class RDoc::Attr
-
-  include RDoc::Generator::Markup
+class RDoc::ClassModule
 
-end
-
-class RDoc::Alias
-
-  include RDoc::Generator::Markup
-
-end
-
-class RDoc::Constant
-
-  include RDoc::Generator::Markup
-
-end
-
-class RDoc::Context
+  ##
+  # Handy wrapper for marking up this class or module's comment
 
-  include RDoc::Generator::Markup
+  def description
+    markup @comment_location
+  end
 
 end
 
@@ -194,12 +147,12 @@ class RDoc::TopLevel
   # command line option to set.
 
   def cvs_url
-    url = RDoc::RDoc.current.options.webcvs
+    url = @store.rdoc.options.webcvs
 
     if /%s/ =~ url then
-      url % @absolute_name
+      url % @relative_name
     else
-      url + @absolute_name
+      url + @relative_name
     end
   end
 

data/lib/rdoc/generator/pot/message_extractor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+##
+# Extracts message from RDoc::Store
+
+class RDoc::Generator::POT::MessageExtractor
+
+  ##
+  # Creates a message extractor for +store+.
+
+  def initialize store
+    @store = store
+    @po = RDoc::Generator::POT::PO.new
+  end
+
+  ##
+  # Extracts messages from +store+, stores them into
+  # RDoc::Generator::POT::PO and returns it.
+
+  def extract
+    @store.all_classes_and_modules.each do |klass|
+      extract_from_klass(klass)
+    end
+    @po
+  end
+
+  private
+
+  def extract_from_klass klass
+    extract_text(klass.comment_location, klass.full_name)
+
+    klass.each_section do |section, constants, attributes|
+      extract_text(section.title ,"#{klass.full_name}: section title")
+      section.comments.each do |comment|
+        extract_text(comment, "#{klass.full_name}: #{section.title}")
+      end
+    end
+
+    klass.each_constant do |constant|
+      extract_text(constant.comment, constant.full_name)
+    end
+
+    klass.each_attribute do |attribute|
+      extract_text(attribute.comment, attribute.full_name)
+    end
+
+    klass.each_method do |method|
+      extract_text(method.comment, method.full_name)
+    end
+  end
+
+  def extract_text text, comment, location = nil
+    return if text.nil?
+
+    options = {
+      :extracted_comment => comment,
+      :references => [location].compact,
+    }
+    i18n_text = RDoc::I18n::Text.new(text)
+    i18n_text.extract_messages do |part|
+      @po.add(entry(part[:paragraph], options))
+    end
+  end
+
+  def entry msgid, options
+    RDoc::Generator::POT::POEntry.new(msgid, options)
+  end
+
+end

data/lib/rdoc/generator/pot/po.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+##
+# Generates a PO format text
+
+class RDoc::Generator::POT::PO
+
+  ##
+  # Creates an object that represents PO format.
+
+  def initialize
+    @entries = {}
+    add_header
+  end
+
+  ##
+  # Adds a PO entry to the PO.
+
+  def add entry
+    existing_entry = @entries[entry.msgid]
+    if existing_entry
+      entry = existing_entry.merge(entry)
+    end
+    @entries[entry.msgid] = entry
+  end
+
+  ##
+  # Returns PO format text for the PO.
+
+  def to_s
+    po = ''
+    sort_entries.each do |entry|
+      po += "\n" unless po.empty?
+      po += entry.to_s
+    end
+    po
+  end
+
+  private
+
+  def add_header
+    add(header_entry)
+  end
+
+  def header_entry
+    comment = <<-COMMENT
+SOME DESCRIPTIVE TITLE.
+Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+This file is distributed under the same license as the PACKAGE package.
+FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+    COMMENT
+
+    content = <<-CONTENT
+Project-Id-Version: PACKAGE VERSEION
+Report-Msgid-Bugs-To:
+PO-Revision-Date: YEAR-MO_DA HO:MI+ZONE
+Last-Translator: FULL NAME <EMAIL@ADDRESS>
+Language-Team: LANGUAGE <LL@li.org>
+Language:
+MIME-Version: 1.0
+Content-Type: text/plain; charset=CHARSET
+Content-Transfer-Encoding: 8bit
+Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;
+    CONTENT
+
+    options = {
+      :msgstr => content,
+      :translator_comment => comment,
+      :flags => ['fuzzy'],
+    }
+    RDoc::Generator::POT::POEntry.new('', options)
+  end
+
+  def sort_entries
+    headers, messages = @entries.values.partition do |entry|
+      entry.msgid.empty?
+    end
+    # TODO: sort by location
+    sorted_messages = messages.sort_by do |entry|
+      entry.msgid
+    end
+    headers + sorted_messages
+  end
+
+end