class CopsDocumentationGenerator
Class for generating documentation of all cops departments @api private
Constants
- CopData
- STRUCTURE
Attributes
Public Class Methods
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
You can append additional information:
callback = ->(data) { required_rails_version(data.cop) } CopsDocumentationGenerator.new(extra_info: { ruby_version: callback }).call
This will insert the string returned from the lambda after the section from RuboCop
itself. See ‘CopsDocumentationGenerator::STRUCTURE` for available sections.
# File lib/rubocop/cops_documentation_generator.rb, line 39 def initialize(departments: [], extra_info: {}, base_dir: Dir.pwd) @departments = departments.map(&:to_sym).sort! @extra_info = extra_info @cops = RuboCop::Cop::Registry.global @config = RuboCop::ConfigLoader.default_configuration @base_dir = base_dir @docs_path = "#{base_dir}/docs/modules/ROOT" FileUtils.mkdir_p("#{@docs_path}/pages") end
Public Instance Methods
# File lib/rubocop/cops_documentation_generator.rb, line 49 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
# File lib/rubocop/cops_documentation_generator.rb, line 77 def check_examples_to_have_the_default_enforced_style!(example_objects, cop) return if example_objects.none? examples_describing_enforced_style = example_objects.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
# File lib/rubocop/cops_documentation_generator.rb, line 168 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
rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
# File lib/rubocop/cops_documentation_generator.rb, line 201 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
# File lib/rubocop/cops_documentation_generator.rb, line 193 def configuration_name(department, name) return name unless name == 'AllowMultilineFinalElement' filename = "#{department_to_basename(department)}.adoc" "xref:#{filename}#allowmultilinefinalelement[AllowMultilineFinalElement]" end
# File lib/rubocop/cops_documentation_generator.rb, line 175 def configurations(department, pars, cop) 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]) [configuration_name(department, name), default, configurable] end cop_subsection('Configurable attributes', cop) + to_table(header, content) end
# File lib/rubocop/cops_documentation_generator.rb, line 328 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
rubocop:enable Metrics/MethodLength
# File lib/rubocop/cops_documentation_generator.rb, line 145 def cop_header(cop) content = +"\n" content << "[##{to_anchor(cop.cop_name)}]\n" content << "== #{cop.cop_name}\n" content << "\n" content end
# File lib/rubocop/cops_documentation_generator.rb, line 368 def cop_status(status) return 'Disabled' unless status status == 'pending' ? 'Pending' : 'Enabled' end
# File lib/rubocop/cops_documentation_generator.rb, line 153 def cop_subsection(title, cop) content = +"\n" content << "[##{to_anchor(title)}-#{to_anchor(cop.cop_name)}]\n" content << "=== #{title}\n" content << "\n" content end
# File lib/rubocop/cops_documentation_generator.rb, line 66 def cops_body(data) check_examples_to_have_the_default_enforced_style!(data.example_objects, data.cop) content = +'' STRUCTURE.each do |section, block| content << instance_exec(data, &block) content << @extra_info[section].call(data) if @extra_info[section] end content end
# File lib/rubocop/cops_documentation_generator.rb, line 62 def cops_of_department(department) cops.with_department(department).sort! end
# File lib/rubocop/cops_documentation_generator.rb, line 161 def example_header(title, cop) content = +"[##{to_anchor(title)}-#{to_anchor(cop.cop_name)}]\n" content << "==== #{title}\n" content << "\n" content end
# File lib/rubocop/cops_documentation_generator.rb, line 92 def examples(example_objects, cop) return '' if example_objects.none? example_objects.each_with_object(cop_subsection('Examples', cop).dup) do |example, content| content << "\n" unless content.end_with?("\n\n") content << example_header(example.name, cop) unless example.name == '' content << code_example(example) end end
# File lib/rubocop/cops_documentation_generator.rb, line 239 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("#{@base_dir}/", '').rstrip end
rubocop:enable Metrics/MethodLength
# File lib/rubocop/cops_documentation_generator.rb, line 308 def print_cop_with_doc(cop) # rubocop:todo Metrics/AbcSize, Metrics/MethodLength cop_config = config.for_cop(cop) non_display_keys = %w[ AutoCorrect Description Enabled StyleGuide Reference Safe SafeAutoCorrect VersionAdded VersionChanged ] pars = cop_config.reject { |k| non_display_keys.include? k } description = 'No documentation' example_objects = safety_objects = see_objects = [] cop_code(cop) do |code_object| description = code_object.docstring unless code_object.docstring.blank? example_objects = code_object.tags('example') safety_objects = code_object.tags('safety') see_objects = code_object.tags('see') end data = CopData.new(cop: cop, description: description, example_objects: example_objects, safety_objects: safety_objects, see_objects: see_objects, config: pars) cops_body(data) end
rubocop:disable Metrics/MethodLength
# File lib/rubocop/cops_documentation_generator.rb, line 287 def print_cops_of_department(department) selected_cops = cops_of_department(department) content = +<<~HEADER //// Do NOT edit this file by hand directly, as it is automatically generated. Please make any necessary changes to the cop documentation within the source files themselves. //// = #{department} HEADER selected_cops.each { |cop| content << print_cop_with_doc(cop) } content << footer_for_department(department) file_name = "#{docs_path}/pages/#{department_to_basename(department)}.adoc" File.open(file_name, 'w') do |file| puts "* generated #{file_name}" file.write("#{content.strip}\n") end end
# File lib/rubocop/cops_documentation_generator.rb, line 348 def print_table_of_contents path = "#{docs_path}/pages/cops.adoc" File.write(path, table_contents) and return unless File.exist?(path) original = File.read(path) content = +"// START_COP_LIST\n\n" content << table_contents content << "\n// END_COP_LIST" content = original.sub(%r{// START_COP_LIST.+// END_COP_LIST}m, content) File.write(path, content) end
rubocop:disable Metrics/MethodLength
# File lib/rubocop/cops_documentation_generator.rb, line 121 def properties(cop) header = [ 'Enabled by default', 'Safe', 'Supports autocorrection', 'Version Added', 'Version Changed' ] autocorrect = if cop.support_autocorrect? context = cop.new.always_autocorrect? ? 'Always' : 'Command-line only' "#{context}#{' (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
# File lib/rubocop/cops_documentation_generator.rb, line 263 def references(cop, see_objects) # rubocop:disable Metrics/AbcSize cop_config = config.for_cop(cop) urls = RuboCop::Cop::MessageAnnotator.new(config, cop.name, cop_config, {}).urls return '' if urls.empty? && see_objects.empty? content = cop_subsection('References', cop) content << urls.map { |url| "* #{url}" }.join("\n") content << "\n" unless urls.empty? content << see_objects.map { |see| "* #{see.name}" }.join("\n") content << "\n" unless see_objects.empty? content end
# File lib/rubocop/cops_documentation_generator.rb, line 114 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
# File lib/rubocop/cops_documentation_generator.rb, line 102 def safety_object(safety_objects, cop) return '' if safety_objects.all? { |s| s.text.blank? } safety_objects.each_with_object(cop_subsection('Safety', cop).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
# File lib/rubocop/cops_documentation_generator.rb, line 364 def table_contents departments.map { |department| table_of_content_for_department(department) }.join("\n") end
# File lib/rubocop/cops_documentation_generator.rb, line 336 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 = to_anchor(cop.cop_name) content << "* xref:#{filename}##{anchor}[#{cop.cop_name}]\n" end content end
HTML anchor are somewhat limited in what characters they can contain, just accept a known-good subset. As long as it’s consistent it doesn’t matter.
Style/AccessModifierDeclarations => styleaccessmodifierdeclarations OnlyFor: [] (default) => onlyfor_-_-_default
# File lib/rubocop/cops_documentation_generator.rb, line 379 def to_anchor(title) title.delete('/').tr(' ', '-').gsub(/[^a-zA-Z0-9-]/, '_').downcase end
rubocop:enable Metrics/CyclomaticComplexity,Metrics/MethodLength
# File lib/rubocop/cops_documentation_generator.rb, line 229 def to_table(header, content) table = ['|===', "| #{header.join(' | ')}\n\n"].join("\n") marked_contents = content.map do |plain_content| # Escape `|` with backslash to prevent the regexp `|` is not used as a table separator. plain_content.map { |c| "| #{c.gsub('|', '\|')}" }.join("\n") end table << marked_contents.join("\n\n") table << "\n|===\n" end
# File lib/rubocop/cops_documentation_generator.rb, line 254 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