Class: Solargraph::Documentor

Inherits:
Object
  • Object
show all
Defined in:
lib/solargraph/documentor.rb

Constant Summary collapse

RDOC_GEMS = 
%w[
  actioncable actionmailbox actionmailer actionpack actiontext actionview
  activejob activemodel activerecord activestorage activesupport railties
]

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(directory, rebuild: false, out: File.new(File::NULL, 'w')) ⇒ Documentor

Returns a new instance of Documentor.



17
18
19
20
21
 
# File 'lib/solargraph/documentor.rb', line 17

def initialize directory, rebuild: false, out: File.new(File::NULL, 'w')
  @directory = directory
  @rebuild = rebuild
  @out = out
end

Class Method Details

.specs_from_bundle(directory) ⇒ Hash

Parameters:

  • directory (String)

Returns:



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/solargraph/documentor.rb', line 60

def self.specs_from_bundle directory
  Solargraph.with_clean_env do
    Dir.chdir directory do
      cmd = [
        'bundle', 'exec', 'ruby', '-e',
        "require 'bundler'; require 'json'; puts Bundler.definition.specs_for([:default]).map { |spec| [spec.name, spec.version] }.to_h.to_json"
      ]
      o, e, s = Open3.capture3(*cmd)
      if s.success?
        o && !o.empty? ? JSON.parse(o.split("\n").last) : {}
      else
        Solargraph.logger.warn e
        raise BundleNotFoundError, "Failed to load gems from bundle at #{directory}"
      end
    end
  end
end

Instance Method Details

#document ⇒ Boolean

Returns True if all specs were found and documented.

Returns:

  • (Boolean) —

    True if all specs were found and documented.



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/solargraph/documentor.rb', line 24

def document
  failures = 0
  Documentor.specs_from_bundle(@directory).each_pair do |name, version|
    yd = YARD::Registry.yardoc_file_for_gem(name, "= #{version}")
    if !yd || @rebuild
      FileUtils.safe_unlink File.join(YardMap::CoreDocs.cache_dir, 'gems', "#{name}-#{version}.ser")
      @out.puts "Documenting #{name} #{version}"
      `yard gems #{name} #{version} #{@rebuild ? '--rebuild' : ''}`
      yd = YARD::Registry.yardoc_file_for_gem(name, "= #{version}")
      # HACK: Ignore errors documenting bundler
      if !yd && name != 'bundler'
        @out.puts "#{name} #{version} YARD documentation failed"
        failures += 1
      end
    end
    if yd && RDOC_GEMS.include?(name)
      cache = File.join(Solargraph::YardMap::CoreDocs.cache_dir, 'gems', "#{name}-#{version}", 'yardoc')
      if !File.exist?(cache) || @rebuild
        @out.puts "Caching custom documentation for #{name} #{version}"
        spec = Gem::Specification.find_by_name(name, "= #{version}")
        Solargraph::YardMap::RdocToYard.run(spec)
      end
    end
  end
  if failures > 0
    @out.puts "#{failures} gem#{failures == 1 ? '' : 's'} could not be documented. You might need to run `bundle install`."
  end
  failures == 0
rescue Solargraph::BundleNotFoundError => e
  @out.puts "[#{e.class}] #{e.message}"
  @out.puts "No bundled gems are available in #{@directory}"
  false
end