class CopsDocumentationGenerator

Class for generating documentation of all cops departments @api private

Attributes

config[R]
cops[R]
departments[R]

Public Class Methods

new(departments: []) click to toggle source

This class will only generate documentation for cops that belong to one of the departments given in the ‘departments` array. E.g. if we only wanted documentation for Lint cops:

CopsDocumentationGenerator.new(departments: ['Lint']).call
# File lib/rubocop/cops_documentation_generator.rb, line 13
def initialize(departments: [])
  @departments = departments.map(&:to_sym).sort!
  @cops = RuboCop::Cop::Registry.global
  @config = RuboCop::ConfigLoader.default_configuration
end

Public Instance Methods

call() click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 19
def call
  YARD::Registry.load!
  departments.each { |department| print_cops_of_department(department) }

  print_table_of_contents
ensure
  RuboCop::ConfigLoader.default_configuration = nil
end

Private Instance Methods

check_examples_to_have_the_default_enforced_style!(examples_object, cop) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 50
def check_examples_to_have_the_default_enforced_style!(examples_object, cop)
  return if examples_object.none?

  examples_describing_enforced_style = examples_object.map(&:name).grep(/EnforcedStyle:/)
  return if examples_describing_enforced_style.none?

  if examples_describing_enforced_style.index { |name| name.match?('default') }.nonzero?
    raise "Put the example with the default EnforcedStyle on top for #{cop.cop_name}"
  end

  return if examples_describing_enforced_style.any? { |name| name.match?('default') }

  raise "Specify the default EnforcedStyle for #{cop.cop_name}"
end
code_example(ruby_code) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 132
def code_example(ruby_code)
  content = +"[source,ruby]\n----\n"
  content << ruby_code.text.gsub('@good', '# good').gsub('@bad', '# bad').strip
  content << "\n----\n"
  content
end
configurable_values(pars, name) click to toggle source

rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength

# File lib/rubocop/cops_documentation_generator.rb, line 157
def configurable_values(pars, name)
  case name
  when /^Enforced/
    supported_style_name = RuboCop::Cop::Util.to_supported_styles(name)
    format_table_value(pars[supported_style_name])
  when 'IndentationWidth'
    'Integer'
  when 'Database'
    format_table_value(pars['SupportedDatabases'])
  else
    case pars[name]
    when String
      'String'
    when Integer
      'Integer'
    when Float
      'Float'
    when true, false
      'Boolean'
    when Array
      'Array'
    else
      ''
    end
  end
end
configurations(pars) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 139
def configurations(pars)
  return '' if pars.empty?

  header = ['Name', 'Default value', 'Configurable values']
  configs = pars
            .each_key
            .reject { |key| key.start_with?('Supported') }
            .reject { |key| key.start_with?('AllowMultipleStyles') }
  content = configs.map do |name|
    configurable = configurable_values(pars, name)
    default = format_table_value(pars[name])
    [name, default, configurable]
  end

  h3('Configurable attributes') + to_table(header, content)
end
cop_code(cop) { |code_object| ... } click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 257
def cop_code(cop)
  YARD::Registry.all(:class).detect do |code_object|
    next unless RuboCop::Cop::Badge.for(code_object.to_s) == cop.badge

    yield code_object
  end
end
cop_status(status) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 294
def cop_status(status)
  return 'Disabled' unless status

  status == 'pending' ? 'Pending' : 'Enabled'
end
cops_body(cop, description, examples_objects, safety_objects, pars) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 36
def cops_body(cop, description, examples_objects, safety_objects, pars) # rubocop:disable Metrics/AbcSize
  check_examples_to_have_the_default_enforced_style!(examples_objects, cop)

  content = h2(cop.cop_name)
  content << required_ruby_version(cop)
  content << properties(cop)
  content << "#{description}\n"
  content << safety_object(safety_objects) if safety_objects.any? { |s| !s.text.blank? }
  content << examples(examples_objects) if examples_objects.any?
  content << configurations(pars)
  content << references(cop)
  content
end
cops_of_department(department) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 32
def cops_of_department(department)
  cops.with_department(department).sort!
end
examples(examples_object) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 65
def examples(examples_object)
  examples_object.each_with_object(h3('Examples').dup) do |example, content|
    content << "\n" unless content.end_with?("\n\n")
    content << h4(example.name) unless example.name == ''
    content << code_example(example)
  end
end
format_table_value(val) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 194
def format_table_value(val)
  value =
    case val
    when Array
      if val.empty?
        '`[]`'
      else
        val.map { |config| format_table_value(config) }.join(', ')
      end
    else
      wrap_backtick(val.nil? ? '<none>' : val)
    end
  value.gsub("#{Dir.pwd}/", '').rstrip
end
h2(title) click to toggle source

rubocop:enable Metrics/MethodLength

# File lib/rubocop/cops_documentation_generator.rb, line 112
def h2(title)
  content = +"\n"
  content << "== #{title}\n"
  content << "\n"
  content
end
h3(title) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 119
def h3(title)
  content = +"\n"
  content << "=== #{title}\n"
  content << "\n"
  content
end
h4(title) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 126
def h4(title)
  content = +"==== #{title}\n"
  content << "\n"
  content
end
print_cop_with_doc(cop) click to toggle source
print_cops_of_department(department) click to toggle source
print_table_of_contents() click to toggle source
properties(cop) click to toggle source

rubocop:disable Metrics/MethodLength

# File lib/rubocop/cops_documentation_generator.rb, line 90
def properties(cop)
  header = [
    'Enabled by default', 'Safe', 'Supports autocorrection', 'Version Added',
    'Version Changed'
  ]
  autocorrect = if cop.support_autocorrect?
                  "Yes#{' (Unsafe)' unless cop.new(config).safe_autocorrect?}"
                else
                  'No'
                end
  cop_config = config.for_cop(cop)
  content = [[
    cop_status(cop_config.fetch('Enabled')),
    cop_config.fetch('Safe', true) ? 'Yes' : 'No',
    autocorrect,
    cop_config.fetch('VersionAdded', '-'),
    cop_config.fetch('VersionChanged', '-')
  ]]
  "#{to_table(header, content)}\n"
end
references(cop) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 218
def references(cop)
  cop_config = config.for_cop(cop)
  urls = RuboCop::Cop::MessageAnnotator.new(config, cop.name, cop_config, {}).urls
  return '' if urls.empty?

  content = h3('References')
  content << urls.map { |url| "* #{url}" }.join("\n")
  content << "\n"
  content
end
required_ruby_version(cop) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 83
def required_ruby_version(cop)
  return '' unless cop.respond_to?(:required_minimum_ruby_version)

  "NOTE: Required Ruby version: #{cop.required_minimum_ruby_version}\n\n"
end
safety_object(safety_object_objects) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 73
def safety_object(safety_object_objects)
  safety_object_objects.each_with_object(h3('Safety').dup) do |safety_object, content|
    next if safety_object.text.blank?

    content << "\n" unless content.end_with?("\n\n")
    content << safety_object.text
    content << "\n"
  end
end
table_contents() click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 290
def table_contents
  departments.map { |department| table_of_content_for_department(department) }.join("\n")
end
table_of_content_for_department(department) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 265
def table_of_content_for_department(department)
  type_title = department[0].upcase + department[1..]
  filename = "#{department_to_basename(department)}.adoc"
  content = +"=== Department xref:#{filename}[#{type_title}]\n\n"
  cops_of_department(department).each do |cop|
    anchor = cop.cop_name.sub('/', '').downcase
    content << "* xref:#{filename}##{anchor}[#{cop.cop_name}]\n"
  end

  content
end
to_table(header, content) click to toggle source

rubocop:enable Metrics/CyclomaticComplexity,Metrics/MethodLength

# File lib/rubocop/cops_documentation_generator.rb, line 185
def to_table(header, content)
  table = ['|===', "| #{header.join(' | ')}\n\n"].join("\n")
  marked_contents = content.map do |plain_content|
    plain_content.map { |c| "| #{c}" }.join("\n")
  end
  table << marked_contents.join("\n\n")
  table << "\n|===\n"
end
wrap_backtick(value) click to toggle source
# File lib/rubocop/cops_documentation_generator.rb, line 209
def wrap_backtick(value)
  if value.is_a?(String)
    # Use `+` to prevent text like `**/*.gemspec`, `spec/**/*` from being bold.
    value.include?('*') ? "`+#{value}+`" : "`#{value}`"
  else
    "`#{value}`"
  end
end