Module: GemDocs::Overview

Defined in:
lib/gem_docs/overview.rb

Constant Summary collapse 

'Gem Overview (extracted from README.org by gem_docs)'

Class Method Summary collapse

Class Method Details

.overview_re ⇒ Object

Return a Regexp that capture any GemDocs-generated overview comment in the main module library file. The Regex requires the comment to come immediately before the module <GemName> line of the libary file, or it will not match.



52
53
54
55
56
57
58
59
60
61
 
# File 'lib/gem_docs/overview.rb', line 52

def self.overview_re
  heads = GemDocs.config.overview_headings
  re_str = "#\\s*" + Regexp.quote(BANNER) + ".*"
  heads.each do |h|
    re_str << "\\*\\s+#{Regexp.escape(h)}.*"
  end
  repo = Repo.from_gemspec
  re_str += "(?=\\n\\s*module\\s+#{repo.module_name})"
  Regexp.new(re_str, Regexp::MULTILINE | Regexp::IGNORECASE)
end

.present? ⇒ Boolean

Returns:

  • (Boolean) 


63
64
65
66
67
68
69
70
 
# File 'lib/gem_docs/overview.rb', line 63

def self.present?
  repo = Repo.from_gemspec
  target = File.join("lib", "#{repo.name}.rb")

  return false unless File.exist?(target)

  File.read(target).match?(overview_re)
end

.write_overview? ⇒ Boolean

Returns String The overview from README per config.

Returns:

  • (Boolean) —

    String The overview from README per config



11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/gem_docs/overview.rb', line 11

def self.write_overview?
  repo = Repo.from_gemspec
  target = File.join("lib", "#{repo.name}.rb")

  return false unless File.exist?(target)

  overview = extract
  return false unless overview

  old_lib = File.read(target)
  old_match = old_lib.match(overview_re)
  old_comment = old_match.to_s

  new_comment = <<~RUBY.chomp
    # #{BANNER}
    #
    #{overview.lines.map { |l| l.match?(/\A\s*\z/) ? '#' : "# #{l.rstrip}" }.join("\n")}
  RUBY
  return false if old_comment == new_comment

  new_lib =
    if old_match
      # There was an overview in the old_lib_content, so replace it with
      # the new_lib_comment.
      old_lib.sub(old_comment, new_comment)
    else
      scanner = StringScanner.new(old_lib)
      if scanner.scan_until(/^module #{repo.module_name}/)
        scanner.pre_match + "\n" + new_comment + "\n" + scanner.matched + scanner.rest
      else
        # No `module GemName` in the file.  Add empty one at the end
        old_lib + "\n" + new_comment + "\nmodule #{repo.module_name}\nend"
      end
    end
  File.write(target, new_lib) > 0
end