boondoc 0.1.0 → 0.2.0

data/lib/boondoc/renderer/docstring.rb

@@ -4,11 +4,11 @@ module Boondoc
   module Renderer
     # Renders a docstring: callouts, body, then one section per kind of tag.
     class Docstring < Base
-      CALLOUTS = { 'deprecated' => 'Deprecated', 'abstract' => 'Abstract', 'note' => 'Note',
-                   'todo' => 'Todo' }.freeze
-      TYPED = { 'yieldparam' => 'Yield parameters', 'yieldreturn' => 'Yield returns',
-                'return' => 'Returns', 'raise' => 'Raises' }.freeze
-      META = { 'since' => 'Since', 'version' => 'Version', 'author' => 'Author', 'api' => 'API' }.freeze
+      CALLOUTS = { "deprecated" => "Deprecated", "abstract" => "Abstract", "note" => "Note",
+                   "todo" => "Todo" }.freeze
+      TYPED = { "yieldparam" => "Yield parameters", "yieldreturn" => "Yield returns",
+                "return" => "Returns", "raise" => "Raises" }.freeze
+      META = { "since" => "Since", "version" => "Version", "author" => "Author", "api" => "API" }.freeze
       HANDLED = (CALLOUTS.keys + TYPED.keys + META.keys +
                  %w[param option yield example see overload private attr attr_reader attr_writer]).freeze
 
@@ -25,9 +25,15 @@ module Boondoc
       # @return [Array<String>] markdown blocks, in order
       def render(docstring)
         [
-          callouts(docstring), text(docstring.text), parameters(docstring), yields(docstring),
+          callouts(docstring),
+          text(docstring.text),
+          parameters(docstring),
+          yields(docstring),
           TYPED.map { |name, title| section(title, docstring.tags_named(name).map { |tag| typed(tag) }) },
-          examples(docstring), see_also(docstring), meta(docstring), overloads(docstring)
+          examples(docstring),
+          see_also(docstring),
+          meta(docstring),
+          overloads(docstring)
         ].flatten.compact.reject(&:empty?)
       end
 
@@ -44,7 +50,7 @@ module Boondoc
       def callouts(docstring)
         docstring.tags.select { |tag| CALLOUTS.key?(tag.tag_name) }.map do |tag|
           body = text(tag.text)
-          label = "**#{CALLOUTS[tag.tag_name]}#{':' unless body.empty?}** #{body}".strip
+          label = "**#{CALLOUTS[tag.tag_name]}#{":" unless body.empty?}** #{body}".strip
           label.lines.map { |line| "> #{line}".rstrip }.join("\n")
         end
       end
@@ -53,53 +59,53 @@ module Boondoc
         "**#{title}:**\n\n#{items.join("\n")}" unless items.empty?
       end
 
-      def item(lead, description, indent: '')
-        line = [lead, description].compact.reject(&:empty?).join(' — ')
+      def item(lead, description, indent: "")
+        line = [lead, description].compact.reject(&:empty?).join(" — ")
         "#{indent}- #{line.gsub("\n", "\n#{indent}  ")}"
       end
 
       def typed(tag)
         types = types(tag)
-        item([tag.name && code(tag.name), types && "(#{types})"].compact.join(' '), text(tag.text))
+        item([tag.name && code(tag.name), types && "(#{types})"].compact.join(" "), text(tag.text))
       end
 
       def parameters(docstring)
-        params = docstring.tags_named('param')
-        options = docstring.tags_named('option')
-        items = params.flat_map { |tag| [typed(tag), *option_items(options, tag.name, '  ')] }
-        [section('Parameters', items), *orphan_options(options, params.map(&:name))]
+        params = docstring.tags_named("param")
+        options = docstring.tags_named("option")
+        items = params.flat_map { |tag| [typed(tag), *option_items(options, tag.name, "  ")] }
+        [section("Parameters", items), *orphan_options(options, params.map(&:name))]
       end
 
       # Options whose hash is not itself documented with @param get their own section.
       def orphan_options(options, param_names)
         orphans = options.reject { |option| param_names.include?(option.name) }
         orphans.map(&:name).uniq.map do |name|
-          section("Options (#{code(name)})", option_items(orphans, name, ''))
+          section("Options (#{code(name)})", option_items(orphans, name, ""))
         end
       end
 
       def option_items(options, name, indent)
         options.select { |option| option.name == name }.map do |option|
           types = types(option)
-          lead = [code(option.key), types && "(#{types})"].compact.join(' ')
+          lead = [code(option.key), types && "(#{types})"].compact.join(" ")
           default = option.default && "(default: #{code(option.default)})"
-          item(lead, [text(option.text), default].compact.reject(&:empty?).join(' '), indent: indent)
+          item(lead, [text(option.text), default].compact.reject(&:empty?).join(" "), indent: indent)
         end
       end
 
       def yields(docstring)
-        items = docstring.tags_named('yield').map do |tag|
-          names = tag.types&.map { |name| code(name) }&.join(', ')
+        items = docstring.tags_named("yield").map do |tag|
+          names = tag.types&.map { |name| code(name) }&.join(", ")
           item(names && "(#{names})", text(tag.text))
         end
-        section('Yields', items)
+        section("Yields", items)
       end
 
       def examples(docstring)
-        tags = docstring.tags_named('example')
+        tags = docstring.tags_named("example")
         return nil if tags.empty?
 
-        ['**Examples:**', *tags.flat_map { |tag| [("*#{tag.name}*" unless tag.name.to_s.empty?), fenced(tag.text)] }]
+        ["**Examples:**", *tags.flat_map { |tag| [("*#{tag.name}*" unless tag.name.to_s.empty?), fenced(tag.text)] }]
       end
 
       def fenced(source)
@@ -107,7 +113,7 @@ module Boondoc
       end
 
       def see_also(docstring)
-        section('See also', docstring.tags_named('see').map { |tag| item(see_link(tag.name.to_s), text(tag.text)) })
+        section("See also", docstring.tags_named("see").map { |tag| item(see_link(tag.name.to_s), text(tag.text)) })
       end
 
       def see_link(name)
@@ -120,18 +126,18 @@ module Boondoc
       def meta(docstring)
         known = META.flat_map { |name, title| docstring.tags_named(name).map { |tag| [title, tag] } }
         other = docstring.tags.reject { |tag| HANDLED.include?(tag.tag_name) }
-                         .map { |tag| [tag.tag_name.tr('_', ' ').capitalize, tag] }
+          .map { |tag| [tag.tag_name.tr("_", " ").capitalize, tag] }
         items = (known + other).map { |title, tag| meta_item(title, tag) }
         items.join("\n") unless items.empty?
       end
 
       def meta_item(title, tag)
         types = types(tag)
-        "- **#{title}:** #{[types && "(#{types})", text(tag.text)].compact.join(' ')}".rstrip
+        "- **#{title}:** #{[types && "(#{types})", text(tag.text)].compact.join(" ")}".rstrip
       end
 
       def overloads(docstring)
-        docstring.tags_named('overload').flat_map do |tag|
+        docstring.tags_named("overload").flat_map do |tag|
           ["**Overload:**\n\n#{ruby("def #{tag.signature}")}", *render(tag.docstring)]
         end
       end

data/lib/boondoc/renderer/index.rb

@@ -28,13 +28,13 @@ module Boondoc
         lines = tree(registry.root, from, 0)
         top = NamespacePage.new(context, registry.root)
         lines << "- [Top level](#{path_map.relative(PathMap::TOP_LEVEL, from)})" if top.content?
-        ['## API reference', lines.join("\n")] unless lines.empty?
+        ["## API reference", lines.join("\n")] unless lines.empty?
       end
 
       def tree(namespace, from, depth)
         namespace.namespaces.select { |child| filter.visible?(child) }.flat_map do |child|
           entry = bullet(linker.link(child, from: from), summary(child, from))
-          ["#{'  ' * depth}#{entry}", *tree(child, from, depth + 1)]
+          ["#{"  " * depth}#{entry}", *tree(child, from, depth + 1)]
         end
       end
 
@@ -42,7 +42,7 @@ module Boondoc
         extras = context.stitcher.files.reject(&:readme)
         return nil if extras.empty?
 
-        ['## Files', extras.map { |file| "- [#{file.title}](#{path_map.relative(file.output, from)})" }.join("\n")]
+        ["## Files", extras.map { |file| "- [#{file.title}](#{path_map.relative(file.output, from)})" }.join("\n")]
       end
     end
   end

data/lib/boondoc/renderer/method_section.rb

@@ -30,8 +30,8 @@ module Boondoc
         reader = accessors.find { |meth| meth.attribute == :reader }
         writer = accessors.find { |meth| meth.attribute == :writer }
         primary = reader || writer
-        name = primary.name.delete_suffix('=')
-        macro = reader && writer ? 'attr_accessor' : "attr_#{primary.attribute}"
+        name = primary.name.delete_suffix("=")
+        macro = (reader && writer) ? "attr_accessor" : "attr_#{primary.attribute}"
         [
           heading("#{primary.separator}#{name}", accessors),
           ruby("#{macro} :#{name}"),
@@ -43,8 +43,8 @@ module Boondoc
       # @param meth [Model::MethodObject]
       # @return [String] the method as it would be defined, such as `def self.build(name)`
       def signature(meth)
-        params = meth.parameters ? "(#{meth.parameters})" : ''
-        "def #{'self.' if meth.scope == :class}#{meth.name}#{params}"
+        params = meth.parameters ? "(#{meth.parameters})" : ""
+        "def #{"self." if meth.scope == :class}#{meth.name}#{params}"
       end
 
       private
@@ -64,7 +64,7 @@ module Boondoc
         lines << "- **Visibility:** #{meth.visibility}" unless meth.visibility == :public
         lines << "- **Alias for:** #{alias_link(meth)}" if meth.alias_for
         aliases = aliases_of(meth)
-        lines << "- **Also known as:** #{aliases.join(', ')}" unless aliases.empty?
+        lines << "- **Also known as:** #{aliases.join(", ")}" unless aliases.empty?
         lines.join("\n") unless lines.empty?
       end
 
@@ -77,7 +77,7 @@ module Boondoc
       def aliases_of(meth)
         aliases = context.aliases(meth.namespace, meth.scope).fetch(meth.name, [])
         aliases.select { |other| filter.visible?(other) }
-               .map { |other| linker.link(other, from: @from, label: code(other.display_name)) }
+          .map { |other| linker.link(other, from: @from, label: code(other.display_name)) }
       end
     end
   end

data/lib/boondoc/renderer/namespace_page.rb

@@ -3,9 +3,9 @@
 module Boondoc
   module Renderer
     # Renders the page for one class or module, or for the top-level namespace.
-    class NamespacePage < Base # rubocop:disable Metrics/ClassLength
-      SCOPES = { class: 'Class methods', instance: 'Instance methods' }.freeze
-      MIXINS = { include: 'Includes', extend: 'Extended by', prepend: 'Prepended by' }.freeze
+    class NamespacePage < Base
+      SCOPES = { class: "Class methods", instance: "Instance methods" }.freeze
+      MIXINS = { include: "Includes", extend: "Extended by", prepend: "Prepended by" }.freeze
       MAX_CONSTANT_LINES = 12
       # A guard against a superclass chain that never ends; real chains are far shorter.
       MAX_SUPERCLASS_CHAIN = 20
@@ -27,10 +27,15 @@ module Boondoc
       # @return [String] the whole page
       def render
         document([
-                   "# #{title}", facts, Docstring.new(context, @namespace, @from).render(@namespace.docstring),
-                   namespaces, constants, attributes,
-                   SCOPES.keys.map { |scope| method_sections(scope) }, inherited_methods
-                 ])
+          "# #{title}",
+          facts,
+          Docstring.new(context, @namespace, @from).render(@namespace.docstring),
+          namespaces,
+          constants,
+          attributes,
+          SCOPES.keys.map { |scope| method_sections(scope) },
+          inherited_methods
+        ])
       end
 
       private
@@ -40,7 +45,7 @@ module Boondoc
       end
 
       def title
-        return 'Top level' if @namespace.root?
+        return "Top level" if @namespace.root?
 
         "#{@namespace.kind.to_s.capitalize}: #{@namespace.path}"
       end
@@ -49,16 +54,16 @@ module Boondoc
 
       def facts
         lines = []
-        lines << "- **Inherits:** #{superclass_chain.join(' < ')}" if @namespace.superclass
+        lines << "- **Inherits:** #{superclass_chain.join(" < ")}" if @namespace.superclass
         lines.concat(mixin_facts)
-        lines << "- **Defined in:** #{source_links.join(', ')}" unless @namespace.files.empty?
+        lines << "- **Defined in:** #{source_links.join(", ")}" unless @namespace.files.empty?
         lines.join("\n") unless lines.empty?
       end
 
       def mixin_facts
         MIXINS.filter_map do |kind, label|
           names = @namespace.mixins[kind]
-          "- **#{label}:** #{names.map { |name| constant_link(name) }.join(', ')}" unless names.empty?
+          "- **#{label}:** #{names.map { |name| constant_link(name) }.join(", ")}" unless names.empty?
         end
       end
 
@@ -89,15 +94,20 @@ module Boondoc
         children = visible(@namespace.namespaces)
         return nil if children.empty?
 
-        ['## Namespaces', children.map { |child| bullet(linker.link(child, from: @from), summary(child, @from)) }
-                                  .join("\n")]
+        ["## Namespaces",
+         children.map { |child|
+           bullet(
+             linker.link(child, from: @from),
+             summary(child, @from)
+           )
+         }.join("\n")]
       end
 
       def constants
         constants = visible(@namespace.constants)
         return nil if constants.empty?
 
-        ['## Constants', *constants.flat_map { |constant| constant_section(constant) }]
+        ["## Constants", *constants.flat_map { |constant| constant_section(constant) }]
       end
 
       def constant_section(constant)
@@ -118,11 +128,11 @@ module Boondoc
       def attributes
         groups = SCOPES.keys.flat_map do |scope|
           visible(context.meths(@namespace, scope)).select(&:attribute)
-                                                   .group_by { |meth| meth.name.delete_suffix('=') }.values
+            .group_by { |meth| meth.name.delete_suffix("=") }.values
         end
         return nil if groups.empty?
 
-        ['## Attributes', *groups.flat_map { |accessors| @methods.render_attribute(accessors) }]
+        ["## Attributes", *groups.flat_map { |accessors| @methods.render_attribute(accessors) }]
       end
 
       def method_sections(scope)
@@ -134,10 +144,10 @@ module Boondoc
 
       def summary_table(meths)
         rows = meths.map do |meth|
-          label = Markdown.table_cell(@methods.signature(meth).delete_prefix('def ').delete_prefix('self.'))
+          label = Markdown.table_cell(@methods.signature(meth).delete_prefix("def ").delete_prefix("self."))
           "| [#{code("#{meth.separator}#{label}")}](#{path_map.href(meth, from: @from)}) | #{summary(meth, @from)} |"
         end
-        ['| Method | Summary |', '| --- | --- |', *rows].join("\n")
+        ["| Method | Summary |", "| --- | --- |", *rows].join("\n")
       end
 
       # Each method is listed under the nearest ancestor that defines it, the
@@ -145,7 +155,7 @@ module Boondoc
       def inherited_methods
         seen = context.meths(@namespace, :instance).to_set(&:name)
         items = registry.ancestors(@namespace).drop(1).filter_map { |ancestor| inherited_from_ancestor(ancestor, seen) }
-        ['## Inherited methods', items.join("\n")] unless items.empty?
+        ["## Inherited methods", items.join("\n")] unless items.empty?
       end
 
       def inherited_from_ancestor(ancestor, seen)
@@ -158,7 +168,7 @@ module Boondoc
         return nil if meths.empty?
 
         links = meths.map { |meth| linker.link(meth, from: @from, label: code(meth.display_name)) }
-        "- From #{linker.link(ancestor, from: @from)}: #{links.join(', ')}"
+        "- From #{linker.link(ancestor, from: @from)}: #{links.join(", ")}"
       end
     end
   end

data/lib/boondoc/stitcher.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require 'pathname'
+require "pathname"
 
 module Boondoc
   # A non-API file (README, changelog, guide) that is copied into the output.
   ExtraFile = Struct.new(:source, :output, :content, :readme, keyword_init: true) do
     # @return [String] the first top-level heading, or the file name
     def title
-      content[/^#\s+(.+?)\s*#*\s*$/, 1] || File.basename(source, '.*')
+      content[/^#\s+(.+?)\s*#*\s*$/, 1] || File.basename(source, ".*")
     end
   end
 
@@ -39,7 +39,7 @@ module Boondoc
     # @return [ExtraFile, nil]
     def find(name)
       files.find { |file| file.source == name } ||
-        files.find { |file| [File.basename(file.source), File.basename(file.source, '.*')].include?(name) }
+        files.find { |file| [File.basename(file.source), File.basename(file.source, ".*")].include?(name) }
     end
 
     # Rewrites relative links and image paths so they still point at the same
@@ -62,7 +62,7 @@ module Boondoc
 
     # Sources are relative to the project root; {Config#extra_files} rejects any outside it.
     def output_name(source)
-      MARKDOWN.match?(source) ? source.sub(MARKDOWN, '.md') : "#{source}.md"
+      MARKDOWN.match?(source) ? source.sub(MARKDOWN, ".md") : "#{source}.md"
     end
 
     def relocate(target, file, embedded:)

data/lib/boondoc/type_parser.rb

@@ -3,7 +3,7 @@
 module Boondoc
   # Splits a YARD type list such as `[String, Hash{Symbol => Array<Integer>}]`.
   module TypeParser
-    OPENERS = { '[' => ']', '<' => '>', '(' => ')', '{' => '}' }.freeze
+    OPENERS = { "[" => "]", "<" => ">", "(" => ")", "{" => "}" }.freeze
     # Duck types naming an operator method that contains bracket characters.
     OPERATOR_DUCK_TYPE = /#(?:<=>|<<|>>|[<>]=?|\[\]=?)/
 
@@ -16,7 +16,7 @@ module Boondoc
     #   when the text does not start with `[`) and the remaining text
     def extract(text)
       text = text.lstrip
-      return [nil, text] unless text.start_with?('[')
+      return [nil, text] unless text.start_with?("[")
 
       close = closing_index(text)
       return [nil, text] unless close
@@ -29,9 +29,9 @@ module Boondoc
     # @param list [String] the text between the outer brackets
     # @return [Array<String>]
     def split(list)
-      types = ['']
+      types = [""]
       each_with_depth(list) do |char, _, depth|
-        next types << +'' if char == ',' && depth.zero?
+        next types << +"" if char == "," && depth.zero?
 
         types[-1] += char
       end
@@ -52,7 +52,7 @@ module Boondoc
       depth = 0
       text.each_char.with_index do |char, index|
         depth += depth_change(text, char, index) unless skip.include?(index)
-        yield char, index, depth
+        yield(char, index, depth)
       end
     end
 
@@ -72,7 +72,7 @@ module Boondoc
       return 0 unless OPENERS.value?(char)
 
       # The `>` of a hash rocket (`=>`) does not close anything.
-      char == '>' && index.positive? && text[index - 1] == '=' ? 0 : -1
+      (char == ">" && index.positive? && text[index - 1] == "=") ? 0 : -1
     end
   end
 end

data/lib/boondoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Boondoc
-  VERSION = '0.1.0'
+  VERSION = "0.2.0"
 end

data/lib/boondoc/writer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'fileutils'
+require "fileutils"
 
 module Boondoc
   # Writes generated pages and removes pages left over from earlier runs.
@@ -9,7 +9,7 @@ module Boondoc
   # own files are ever deleted or silently overwritten. A page whose content has
   # not changed is not written again.
   class Writer
-    MANIFEST = '.boondoc-manifest'
+    MANIFEST = ".boondoc-manifest"
 
     # @param output_dir [String] absolute path of the output directory
     # @param reporter [Reporter]
@@ -84,10 +84,10 @@ module Boondoc
     #   outside the output directory
     def unsafe(path)
       full = File.expand_path(path, @output_dir)
-      return "it is outside #{@output_dir}" unless full.start_with?(File.join(@output_dir, ''))
+      return "it is outside #{@output_dir}" unless full.start_with?(File.join(@output_dir, ""))
 
       # The symlink check below resolves `..` by name, but the file system follows a symlink first.
-      return 'it contains `..`' if path.split('/').include?('..')
+      return "it contains `..`" if path.split("/").include?("..")
 
       link = Containment.symlink_between(full, @output_dir)
       "#{link} is a symlink" if link
@@ -102,9 +102,10 @@ module Boondoc
       end
       return if conflicts.empty?
 
-      raise Error, "refusing to overwrite #{conflicts.size} file(s) that boondoc did not generate " \
-                   "(#{conflicts.first(5).join(', ')}#{', ...' if conflicts.size > 5}). " \
-                   'Use --force to overwrite, or choose another --output directory.'
+      raise Error,
+        "refusing to overwrite #{conflicts.size} file(s) that boondoc did not generate " \
+        "(#{conflicts.first(5).join(", ")}#{", ..." if conflicts.size > 5}). " \
+        "Use --force to overwrite, or choose another --output directory."
     end
 
     # True when a case-insensitive filesystem maps the path onto a page Boondoc wrote before.
@@ -120,8 +121,10 @@ module Boondoc
       paths.group_by(&:downcase).each_value do |group|
         next if group.size == 1
 
-        @reporter.warn("#{group.sort.join(' and ')} differ only by case and will collide on case-insensitive " \
-                       'filesystems; rename one of them')
+        @reporter.warn(
+          "#{group.sort.join(" and ")} differ only by case and will collide on case-insensitive " \
+          "filesystems; rename one of them"
+        )
       end
     end
 

data/lib/boondoc/yard_bridge.rb

@@ -41,13 +41,13 @@ module Boondoc
     private
 
     def load_yard
-      require 'yard'
+      require "yard"
     rescue LoadError
       raise Error, "--yard-macros needs the yard gem. Add `gem 'yard'` to your Gemfile or run `gem install yard`."
     end
 
     def yard_objects
-      namespaces = ::YARD::Registry.all(:module, :class).sort_by { |object| object.path.count(':') }
+      namespaces = ::YARD::Registry.all(:module, :class).sort_by { |object| object.path.count(":") }
       namespaces + ::YARD::Registry.all(:constant, :method)
     end
 
@@ -71,7 +71,7 @@ module Boondoc
     end
 
     def relative(file)
-      prefix = File.join(@root, '')
+      prefix = File.join(@root, "")
       file.start_with?(prefix) ? file.delete_prefix(prefix) : file
     end
 
@@ -92,18 +92,23 @@ module Boondoc
     end
 
     def build_method(yard_object, name, namespace)
-      attribute = (name.end_with?('=') ? :writer : :reader) if yard_object.is_attribute?
-      Model::MethodObject.new(name, namespace, scope: yard_object.scope, attribute: attribute,
-                                               parameters: parameters(yard_object))
+      attribute = (name.end_with?("=") ? :writer : :reader) if yard_object.is_attribute?
+      Model::MethodObject.new(
+        name,
+        namespace,
+        scope: yard_object.scope,
+        attribute: attribute,
+        parameters: parameters(yard_object)
+      )
     end
 
     def parameters(yard_object)
       list = yard_object.parameters.map do |name, default|
         next name.to_s unless default
 
-        name.to_s.end_with?(':') ? "#{name} #{default}" : "#{name} = #{default}"
+        name.to_s.end_with?(":") ? "#{name} #{default}" : "#{name} = #{default}"
       end
-      list.empty? ? nil : list.join(', ')
+      list.empty? ? nil : list.join(", ")
     end
 
     def docstring(yard_object)