class RDoc::Generator::JsonIndex

JsonIndex 生成器旨在作为 HTML 生成器的补充，并生成 JSON 搜索索引。此生成器源自 Vladimir Kolesnikov 的 sdoc，并包含他编写的逐字代码。

此生成器旨在与常规 HTML 生成器一起使用

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

索引格式¶ ↑

索引作为 JSON 文件输出，并赋值给全局变量 search_data。其结构为

var search_data = {
  "index": {
    "searchIndex":
      ["a", "b", ...],
    "longSearchIndex":
      ["a", "a::b", ...],
    "info": [
      ["A", "A", "A.html", "", ""],
      ["B", "A::B", "A::B.html", "", ""],
      ...
    ]
  }
}

同一个项目在 searchIndex、longSearchIndex 和 info 字段中描述。searchIndex 字段包含项目的短名称，longSearchIndex 字段包含 full_name（如果适用），而 info 字段包含项目的名称、full_name、路径、参数以及项目注释的片段。

许可¶ ↑

特此授予任何获得本软件和相关文档文件（“软件”）副本的人员免费许可，以不受限制地处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本的权利，并允许向接受本软件的人员提供本软件，但须遵守以下条件

本软件按“原样”提供，不作任何明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和非侵权性的保证。在任何情况下，作者或版权持有者均不对任何索赔、损害或其他责任负责，无论是在合同、侵权或其他方面的诉讼中，因本软件或使用或以其他方式处理本软件而引起或与之相关的责任。

常量

SEARCH_INDEX_FILE: 搜索索引在生成的输出中的位置

公共类方法

new(parent_generator, options) 点击切换源代码

创建一个新的生成器。parent_generator 用于确定输出索引中链接的 class_dir 和 file_dir。

options 是传递给父生成器的相同选项。

# File rdoc/generator/json_index.rb, line 94
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

公共实例方法

build_index() 点击切换源代码

将 JSON 索引构建为哈希。

# File rdoc/generator/json_index.rb, line 110
def build_index
  reset @store.all_files.sort, @store.all_classes_and_modules.sort

  index_classes
  index_methods
  index_pages

  { :index => @index }
end

class_dir() 点击切换源代码

类写入的目录

# File rdoc/generator/json_index.rb, line 271
def class_dir
  @parent_generator.class_dir
end

debug_msg(*msg) 点击切换源代码

如果启用了调试，则输出进度信息

# File rdoc/generator/json_index.rb, line 123
def debug_msg *msg
  return unless $DEBUG_RDOC
  $stderr.puts(*msg)
end

file_dir() 点击切换源代码

文件写入的目录

# File rdoc/generator/json_index.rb, line 278
def file_dir
  @parent_generator.file_dir
end

generate() 点击切换源代码

将 JSON 索引写入磁盘

# File rdoc/generator/json_index.rb, line 131
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

generate_gzipped() 点击切换源代码

使用 gzip 压缩 search_index.js 文件

# File rdoc/generator/json_index.rb, line 166
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

index_classes() 点击切换源代码

将类和模块添加到索引

# File rdoc/generator/json_index.rb, line 211
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

index_methods() 点击切换源代码

将方法添加到索引

# File rdoc/generator/json_index.rb, line 230
def index_methods
  debug_msg "  generating method search index"

  list = @classes.uniq.flat_map do |klass|
    klass.method_list
  end.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

index_pages() 点击切换源代码

将页面添加到索引

# File rdoc/generator/json_index.rb, line 251
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

search_string(string) 点击切换源代码

删除空白并使 string 小写

# File rdoc/generator/json_index.rb, line 296
def search_string string
  string.downcase.gsub(/\s/, '')
end