core_docs 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ef9c9b9dc66c55c7cfa891c263014f2c2e76d7eb
+  data.tar.gz: 987df53f273c819846120fcc6f09b8274cc1cbec
+SHA512:
+  metadata.gz: db62934c09ab1be4ca56cc44a93a95e1f1908a3cc41259cd49044d4cc5d72e8a5ce8d263ba94691ef76aef61db6c8259e81fb04aeb1eaef20a4f7c10b7752d5e
+  data.tar.gz: b23f4960d820ab46968dca9d17bb8ab6ff2644ee9e393f569df1228ea1a61e6282194ce847c2571ccdbece946f95dce8965863680409be0cfba81c5de1dbff5d

data/.gitignore

@@ -0,0 +1,10 @@
+Makefile
+*.so
+*.o
+*.def
+doc/
+pkg/
+.yardoc/
+*.gem
+Gemfile.lock
+*~

data/.travis.yml

@@ -0,0 +1,13 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1
+  - ruby-head
+
+script:
+  - rake spec
+
+branches:
+  only:
+    - master

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+Core Docs changelog
+===================
+
+### v0.9.0
+
+* Ported from pry-doc
+* Remove 1.9, add 2.2, and rebuild 2.1, 2.0 docs
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gemspec
+

data/LICENSE

@@ -0,0 +1,25 @@
+License
+-------
+
+(The MIT License)
+
+Copyright (c) 2013 John Mair (banisterfiend)
+
+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.

data/README.md

@@ -0,0 +1,18 @@
+MRI Core Docs
+=============
+
+Core Docs is a fork from [pry-doc](https://github.com/pry/pry-doc) that separates its functionality from the pry repl.
+
+Experimental, don't consider this battle-proof.
+
+
+TODO
+----
+
+Polish and get specs to run.
+
+
+License
+-------
+
+The project uses the MIT Licencse. See LICENSE file for more information.

data/Rakefile

@@ -0,0 +1,107 @@
+dlext = RbConfig::CONFIG['DLEXT']
+direc = File.dirname(__FILE__)
+
+PROJECT_NAME = "core_docs"
+
+require 'latest_ruby'
+require 'rake/clean'
+require "#{direc}/lib/#{PROJECT_NAME}/version"
+
+desc "run tests"
+task :test do
+  sh "bacon -k #{direc}/spec/core_docs_spec.rb"
+end
+task :spec => :test
+
+task :default => :test
+
+desc "reinstall gem"
+task :reinstall => :gems do
+  sh "gem uninstall core_docs" rescue nil
+  sh "gem install #{direc}/pkg/core_docs-#{CoreDocs::VERSION}.gem"
+end
+
+desc "build all platform gems at once"
+task :gems => :rmgems do
+  mkdir_p "pkg"
+  sh 'gem build *.gemspec'
+  mv "core_docs-#{CoreDocs::VERSION}.gem", "pkg"
+end
+
+desc "remove all platform gems"
+task :rmgems do
+  rm_rf 'pkg'
+end
+
+desc "Build gemspec"
+task :gemspec => "ruby:gemspec"
+
+desc "Show version"
+task :version do
+  puts "CoreDocs version: #{CoreDocs::VERSION}"
+end
+
+desc "build and push latest gems"
+task :pushgems => :gems do
+  chdir("#{direc}/pkg") do
+    Dir["*.gem"].each do |gemfile|
+      sh "gem push #{gemfile}"
+    end
+  end
+end
+
+def download_ruby(ruby)
+  system "mkdir rubies"
+  system "wget #{ ruby.link } --directory-prefix=rubies --no-clobber"
+  File.join('rubies', ruby.filename)
+end
+
+def unpackage_ruby(path)
+  system "mkdir rubies/ruby"
+  system "tar xzvf #{ path } --directory=rubies/ruby"
+end
+
+def cd_into_ruby
+  Dir.chdir(Dir['rubies/ruby/*'].first)
+end
+
+def generate_yard
+  system %{
+    bash -c "paste <(find . -maxdepth 1 -name '*.c') <(find ext -name '*.c') |
+      xargs yardoc --no-output"
+  }
+end
+
+def replace_existing_docs(ver)
+  target_dir = "../../../lib/core_docs/core_docs_#{ ver }"
+  system %|mkdir -p #{ target_dir } && cp -r .yardoc/* #{ target_dir }|
+  Dir.chdir(File.expand_path(File.dirname(__FILE__)))
+end
+
+def clean_up
+  system "rm -rf rubies"
+end
+
+def generate_docs_for(ruby_ver, latest_ruby)
+  path = download_ruby(latest_ruby)
+  unpackage_ruby(path)
+  cd_into_ruby
+  generate_yard
+  replace_existing_docs(ruby_ver)
+  clean_up
+end
+
+desc "Generate the latest Ruby 2.0 docs"
+task "gen20" do
+  generate_docs_for('20', Latest.ruby20)
+end
+
+desc "Generate the latest Ruby 2.1 docs"
+task "gen21" do
+  generate_docs_for('21', Latest.ruby21)
+end
+
+desc "Generate the latest Ruby 2.2 docs"
+task "gen22" do
+  generate_docs_for('22', Latest.ruby22)
+end

data/core_docs.gemspec

@@ -0,0 +1,27 @@
+require './lib/core_docs/version.rb'
+
+Gem::Specification.new do |s|
+  s.name = "core_docs"
+  s.version = CoreDocs::VERSION
+
+  s.authors = ["John Mair (banisterfiend)", "Jan Lelis (non-pry version)"]
+  s.email = ["jrmair@gmail.com", "mail@janlelis.de"]
+  s.summary = 'Provides YARD and extended documentation support for Pry'
+  s.description = <<DESCR
+Pry Doc is a Pry REPL plugin. It provides extended documentation support for the
+REPL by means of improving the `show-doc` and `show-source` commands. With help
+of the plugin the commands are be able to display the source code and the docs
+of Ruby methods and classes implemented in C.
+documentation
+DESCR
+  s.homepage = "https://github.com/janlelis/core_docs"
+  s.license = 'MIT'
+
+  s.require_paths = ["lib"]
+  s.files = `git ls-files`.split("\n")
+
+  s.required_ruby_version = "~> 2.0"
+  s.add_dependency 'yard', "~> 0.8"
+  s.add_development_dependency 'latest_ruby', "~> 0.0"
+  s.add_development_dependency 'bacon', "~> 1.1"
+end

data/lib/core_docs.rb

@@ -0,0 +1,228 @@
+# based on pry-doc.rb
+# (C) John Mair (banisterfiend); MIT license
+
+direc = File.dirname(__FILE__)
+
+require "#{direc}/core_docs/version"
+require "yard"
+
+module CoreDocs
+  def self.load_yardoc(version)
+    path = "#{File.dirname(__FILE__)}/core_docs/core_docs_#{ version }"
+    YARD::Registry.load_yardoc(path)
+  end
+end
+
+case RUBY_VERSION
+when /\A2\.1/
+  CoreDocs.load_yardoc('21')
+else
+  CoreDocs.load_yardoc('20')
+end
+
+  # do not use pry-doc if rbx is active
+  # if !Object.const_defined?(:RUBY_ENGINE) || RUBY_ENGINE !~ /rbx/
+  #   self.config.has_pry_doc = true
+  # end
+
+module CoreDocs
+  module MethodInfo
+
+    # Convert a method object into the `Class#method` string notation.
+    # @param [Method, UnboundMethod] meth
+    # @return [String] The method in string receiver notation.
+    # @note This mess is needed in order to support all the modern Rubies. YOU
+    #   must figure out a better way to distinguish between class methods and
+    #   instance methods.
+    def self.receiver_notation_for(meth)
+      match = meth.inspect.match(/\A#<(?:Unbound)?Method: (.+)([#\.].+)>\z/)
+      owner = meth.owner.to_s.sub(/#<.+?:(.+?)>/, '\1')
+      name = match[2]
+      name.sub!('#', '.') if match[1] =~ /\A#<Class:/
+      owner + name
+    end
+
+    # Retrives aliases of a method
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [Array] The aliases of a method if it exists
+    #                 otherwise, return empty array
+    def self.aliases(meth)
+      # host        = is_singleton?(meth) ? meth.receiver : meth.owner
+      # method_type = is_singleton?(meth) ? :method : :instance_method
+
+      # methods = Pry::Method.send(:all_from_common, host, method_type, false).
+      #                       map { |m| m.instance_variable_get(:@method) }
+
+      # methods.select { |m| host.send(method_type,m.name) == host.send(method_type,meth.name) }.
+      #         reject { |m| m.name == meth.name }.
+      #         map    { |m| host.send(method_type,m.name) }
+      []
+    end
+
+    # Checks whether method is a singleton (i.e class method)
+    # @param [Method, UnboundMethod] meth
+    # @param [Boolean] true if singleton
+    def self.is_singleton?(meth)
+      receiver_notation_for(meth).include?('.')
+    end
+
+    # Check whether the file containing the method is already cached.
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [Boolean] Whether the method is cached.
+    def self.cached?(meth)
+      !!registry_lookup(meth)
+    end
+
+    def self.registry_lookup(meth)
+      obj = YARD::Registry.at(receiver_notation_for(meth))
+      if obj.nil?
+        if !(aliases = aliases(meth)).empty?
+          obj = YARD::Registry.at(receiver_notation_for(aliases.first))
+        elsif meth.owner == Kernel
+          # YARD thinks that some methods are on Object when
+          # they're actually on Kernel; so try again on Object if Kernel fails.
+          obj = YARD::Registry.at("Object##{meth.name}")
+        end
+      end
+      obj
+    end
+
+    # Retrieve the YARD object that contains the method data.
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [YARD::CodeObjects::MethodObject] The YARD data for the method.
+    def self.info_for(meth)
+      cache(meth)
+      registry_lookup(meth)
+    end
+
+    # Determine whether a method is an eval method.
+    # @return [Boolean] Whether the method is an eval method.
+    def self.is_eval_method?(meth)
+      file, _ = meth.source_location
+      if file =~ /(\(.*\))|<.*>/
+        true
+      else
+        false
+      end
+    end
+
+    # Attempts to find the c source files if method belongs to a gem
+    # and use YARD to parse and cache the source files for display
+    #
+    # @param [Method, UnboundMethod] meth The method object.
+    def self.parse_and_cache_if_gem_cext(meth)
+      if gem_dir = find_gem_dir(meth)
+        if c_files_found?(gem_dir)
+          warn "Scanning and caching *.c files..."
+          YARD.parse("#{gem_dir}/**/*.c")
+        end
+      end
+    end
+
+    # @param [String] root directory path of gem that method belongs to
+    # @return [Boolean] true if c files exist?
+    def self.c_files_found?(gem_dir)
+      Dir.glob("#{gem_dir}/**/*.c").count > 0
+    end
+
+    # @return [Object] The host of the method (receiver or owner).
+    def self.method_host(meth)
+      is_singleton?(meth) && Module === meth.receiver ? meth.receiver : meth.owner
+    end
+
+    # FIXME: this is unnecessarily limited to ext/ and lib/ folders
+    # @return [String] The root folder of a given gem directory.
+    def self.gem_root(dir)
+      if index = dir.rindex(/\/(?:lib|ext)(?:\/|$)/)
+        dir[0..index-1]
+      end
+    end
+
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [String] root directory path of gem that method belongs to,
+    #                  nil if could not be found
+    def self.find_gem_dir(meth)
+      # host = method_host(meth)
+
+      # begin
+      #   host_source_location, _ =  WrappedModule.new(host).source_location
+      #   break if host_source_location != nil
+      #   return unless host.name
+      #   host = eval(host.namespace_name)
+      # end while host
+
+      # # we want to exclude all source_locations that aren't gems (i.e
+      # # stdlib)
+      # if host_source_location && host_source_location =~ %r{/gems/}
+      #   gem_root(host_source_location)
+      # else
+
+        # the WrappedModule approach failed, so try our backup approach
+        gem_dir_from_method(meth)
+      # end
+    end
+
+    # Try to guess what the gem name will be based on the name of the module.
+    # We try a few approaches here depending on the `guess` parameter.
+    # @param [String] name The name of the module.
+    # @param [Fixnum] guess The current guessing approach to use.
+    # @return [String, nil] The guessed gem name, or `nil` if out of guesses.
+    def self.guess_gem_name_from_module_name(name, guess)
+      case guess
+      when 0
+        name.downcase
+      when 1
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('_')
+      when 2
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('_').sub("_", "-")
+      when 3
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('-')
+      when 4
+        name
+      else
+        nil
+      end
+    end
+
+    # Try to recover the gem directory of a gem based on a method object.
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [String, nil] The located gem directory.
+    def self.gem_dir_from_method(meth)
+      guess = 0
+
+      host = method_host(meth)
+      return unless host.name
+      root_module_name = host.name.split("::").first
+      while gem_name = guess_gem_name_from_module_name(root_module_name, guess)
+        matches = $LOAD_PATH.grep %r{/gems/#{gem_name}} if !gem_name.empty?
+        if matches && matches.any?
+          return gem_root(matches.first)
+        else
+          guess += 1
+        end
+      end
+
+      nil
+    end
+
+    # Cache the file that holds the method or return immediately if file is
+    # already cached. Return if the method cannot be cached -
+    # i.e is a C stdlib method.
+    # @param [Method, UnboundMethod] meth The method object.
+    def self.cache(meth)
+      file, _ = meth.source_location
+
+      return if is_eval_method?(meth)
+      return if cached?(meth)
+
+      if !file
+        parse_and_cache_if_gem_cext(meth)
+        return
+      end
+
+      log.enter_level(Logger::FATAL) do
+        YARD.parse(file)
+      end
+    end
+  end
+end