boondoc 0.1.0

data/lib/boondoc/preview.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Serves generated docs locally using the `gh markdown-preview` extension of
+  # the GitHub CLI.
+  #
+  # The previewer resolves links relative to the directory it was started in,
+  # so it is always started from inside the output directory.
+  class Preview
+    EXTENSION = 'yusukebe/gh-markdown-preview'
+    DEFAULT_HOST = '127.0.0.1'
+    LOOPBACK_HOSTS = %w[::1 localhost].freeze
+    SILENT = { out: File::NULL, err: File::NULL }.freeze
+
+    # @param directory [String] the directory holding the generated docs
+    # @param host [String] address the previewer binds to
+    # @param port [Integer, nil] port to listen on; the previewer's default when nil
+    # @yieldreturn [Boolean] whether the extension may be installed; asked only
+    #   when it is missing
+    def initialize(directory, host: DEFAULT_HOST, port: nil, &confirm_install)
+      @directory = directory
+      @host = host
+      @port = port
+      @confirm_install = confirm_install
+    end
+
+    # Starts the previewer and blocks until it exits.
+    #
+    # @return [void]
+    # @raise [Error] when the docs, the GitHub CLI, or the extension are missing
+    def start
+      raise Error, "#{@directory} does not exist; run `boondoc` first to generate the docs" unless docs?
+      raise Error, 'serve needs the GitHub CLI (gh); see https://cli.github.com' unless gh?
+
+      install unless extension?
+      warn_exposed unless loopback?
+      serve
+    end
+
+    private
+
+    def loopback?
+      LOOPBACK_HOSTS.include?(@host) || @host.start_with?('127.')
+    end
+
+    # The extension answers `/__/md?path=` for any path, not only the docs, and
+    # does not check the Host header, so whoever can reach the port can read
+    # every file the current user can.
+    def warn_exposed
+      warn "boondoc: serving on #{@host} exposes the preview to the network. gh markdown-preview will " \
+           'return any file the current user can read, not only the docs. Use the default 127.0.0.1 ' \
+           'unless everyone who can reach this machine is trusted.'
+    end
+
+    def docs?
+      File.directory?(@directory)
+    end
+
+    def gh?
+      system('gh', '--version', **SILENT) == true
+    end
+
+    def extension?
+      system('gh', 'markdown-preview', '--version', **SILENT) == true
+    end
+
+    def install
+      manual = "install it with `gh extension install #{EXTENSION}`"
+      raise Error, "serve needs the gh markdown-preview extension; #{manual}" unless @confirm_install&.call
+      raise Error, "could not install the extension; #{manual}" unless system('gh', 'extension', 'install', EXTENSION)
+    end
+
+    def serve
+      command = ['gh', 'markdown-preview', '--host', @host]
+      command.push('--port', @port.to_s) if @port
+      system(*command, chdir: @directory)
+    rescue Interrupt
+      nil
+    end
+  end
+end

data/lib/boondoc/rake_task.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'rake/tasklib'
+require 'boondoc'
+
+module Boondoc
+  # Defines a Rake task that generates the documentation.
+  #
+  # @example
+  #   require 'boondoc/rake_task'
+  #
+  #   Boondoc::RakeTask.new(:docs) do |t|
+  #     t.options = { output: 'docs', files: ['CHANGELOG.md'], strict: true }
+  #   end
+  class RakeTask < ::Rake::TaskLib
+    # @return [Symbol] the task name
+    attr_accessor :name
+    # @return [Hash{Symbol => Object}] options passed to {Config.load}
+    attr_accessor :options
+
+    # @param name [Symbol]
+    # @yieldparam task [RakeTask] the task, for setting {#options}
+    def initialize(name = :docs)
+      super()
+      @name = name
+      @options = {}
+      yield self if block_given?
+      define
+    end
+
+    private
+
+    def define
+      desc 'Generate markdown documentation with boondoc'
+      task(name) { Generator.new(Config.load(options)).run }
+    end
+  end
+end

data/lib/boondoc/references.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Expands YARD reference docstrings: `(see Foo#bar)` as a whole docstring, or
+  # as the text of a tag such as `@param (see Foo#bar)`.
+  class References
+    SEE = /\A\(see (\S+)\)\z/
+
+    # @param registry [Model::Registry]
+    def initialize(registry)
+      @registry = registry
+    end
+
+    # @return [void]
+    def expand
+      @visited = {}.compare_by_identity
+      @registry.each { |object| expand_object(object) }
+    end
+
+    private
+
+    # Targets are expanded before they are copied, so chains such as
+    # `(see B)` -> `(see C)` work in any order. A cycle stops at the object
+    # already being expanded.
+    def expand_object(object) # rubocop:disable Metrics/MethodLength
+      return if @visited.key?(object)
+
+      @visited[object] = true
+      docstring = object.docstring
+      tags = docstring.tags.flat_map { |tag| expand_tag(object, tag) }
+      text = docstring.text
+      target = referenced(object, text.strip)
+      if target
+        text = target.docstring.text
+        tags += inherited_tags(target, tags)
+      end
+      object.docstring = Model::Docstring.new(text, tags, docstring.directives)
+    end
+
+    def inherited_tags(target, own_tags)
+      own = own_tags.map(&:tag_name)
+      target.docstring.tags.reject { |tag| own.include?(tag.tag_name) }
+    end
+
+    def expand_tag(object, tag)
+      target = referenced(object, tag.text.to_s.strip)
+      target ? target.docstring.tags_named(tag.tag_name) : [tag]
+    end
+
+    def referenced(object, text)
+      match = SEE.match(text)
+      target = match && @registry.resolve(object, match[1])
+      return nil if target.nil? || target.equal?(object)
+
+      expand_object(target)
+      target
+    end
+  end
+end

data/lib/boondoc/renderer/base.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Classes that turn the model into markdown.
+  module Renderer
+    # Shared helpers for all renderers.
+    class Base
+      # @param context [Context]
+      def initialize(context)
+        @context = context
+      end
+
+      private
+
+      attr_reader :context
+
+      def registry = context.registry
+      def filter = context.filter
+      def linker = context.linker
+      def path_map = context.path_map
+
+      def code(text)
+        "`#{text}`"
+      end
+
+      # A fenced Ruby block whose fence is longer than any fence inside the source.
+      def ruby(source)
+        longest = source.scan(/^\s*(`{3,})/).flatten.map(&:size).max || 2
+        fence = '`' * [3, longest + 1].max
+        "#{fence}ruby\n#{source}\n#{fence}"
+      end
+
+      # Joins blocks into a document with exactly one blank line between them.
+      def document(blocks)
+        blocks.flatten.compact.map { |block| block.sub(/\A\n+/, '').rstrip }.reject(&:empty?).join("\n\n") << "\n"
+      end
+
+      # A one-line summary of an object, with references resolved.
+      def summary(object, from)
+        text = linker.text(object.docstring.summary, object: object, from: from)
+        text = "**Deprecated.** #{text}".strip if object.docstring.tag?('deprecated')
+        Markdown.table_cell(text)
+      end
+
+      def bullet(link, summary)
+        summary.empty? ? "- #{link}" : "- #{link} — #{summary}"
+      end
+    end
+  end
+end

data/lib/boondoc/renderer/docstring.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+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
+      HANDLED = (CALLOUTS.keys + TYPED.keys + META.keys +
+                 %w[param option yield example see overload private attr attr_reader attr_writer]).freeze
+
+      # @param context [Context]
+      # @param object [Model::CodeObject] the object being documented
+      # @param from [String] the output file being written
+      def initialize(context, object, from)
+        super(context)
+        @object = object
+        @from = from
+      end
+
+      # @param docstring [Model::Docstring]
+      # @return [Array<String>] markdown blocks, in order
+      def render(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)
+        ].flatten.compact.reject(&:empty?)
+      end
+
+      private
+
+      def text(text)
+        linker.text(text, object: @object, from: @from).strip
+      end
+
+      def types(tag)
+        linker.types(tag.types, object: @object, from: @from)
+      end
+
+      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.lines.map { |line| "> #{line}".rstrip }.join("\n")
+        end
+      end
+
+      def section(title, items)
+        "**#{title}:**\n\n#{items.join("\n")}" unless items.empty?
+      end
+
+      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))
+      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))]
+      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, ''))
+        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(' ')
+          default = option.default && "(default: #{code(option.default)})"
+          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(', ')
+          item(names && "(#{names})", text(tag.text))
+        end
+        section('Yields', items)
+      end
+
+      def examples(docstring)
+        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)] }]
+      end
+
+      def fenced(source)
+        source.match?(/\A\s*(?:```|~~~)/) ? source : ruby(source)
+      end
+
+      def see_also(docstring)
+        section('See also', docstring.tags_named('see').map { |tag| item(see_link(tag.name.to_s), text(tag.text)) })
+      end
+
+      def see_link(name)
+        return "<#{name}>" if Linker::URL.match?(name)
+
+        found = registry.resolve(@object, name)
+        found ? linker.link(found, from: @from, label: code(name)) : text(name)
+      end
+
+      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] }
+        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
+      end
+
+      def overloads(docstring)
+        docstring.tags_named('overload').flat_map do |tag|
+          ["**Overload:**\n\n#{ruby("def #{tag.signature}")}", *render(tag.docstring)]
+        end
+      end
+    end
+  end
+end

data/lib/boondoc/renderer/index.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Boondoc
+  module Renderer
+    # Renders the index page (README plus tables of contents) and stitched files.
+    class Index < Base
+      # @return [String] the index page
+      def render
+        from = context.config.index
+        readme = context.stitcher.readme
+        intro = readme ? file_body(readme) : "# #{context.config.title}"
+        document([intro, api(from), files(from)])
+      end
+
+      # @param file [ExtraFile]
+      # @return [String] a stitched file with its links and references resolved
+      def render_file(file)
+        document([file_body(file)])
+      end
+
+      private
+
+      def file_body(file)
+        linker.text(context.stitcher.relocated_content(file), object: registry.root, from: file.output, assets: false)
+      end
+
+      def api(from)
+        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?
+      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)]
+        end
+      end
+
+      def files(from)
+        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")]
+      end
+    end
+  end
+end

data/lib/boondoc/renderer/method_section.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Boondoc
+  module Renderer
+    # Renders the detail section for one method or one attribute.
+    class MethodSection < Base
+      # @param context [Context]
+      # @param from [String] the output file being written
+      def initialize(context, from)
+        super(context)
+        @from = from
+      end
+
+      # @param meth [Model::MethodObject]
+      # @return [Array<String>] markdown blocks
+      def render(meth)
+        [
+          heading(meth.display_name, [meth]),
+          ruby(signature(meth)),
+          facts(meth),
+          *Docstring.new(context, meth, @from).render(meth.docstring)
+        ]
+      end
+
+      # Renders a reader and/or writer as a single attribute entry.
+      #
+      # @param accessors [Array<Model::MethodObject>] the reader, the writer, or both
+      # @return [Array<String>] markdown blocks
+      def render_attribute(accessors)
+        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}"
+        [
+          heading("#{primary.separator}#{name}", accessors),
+          ruby("#{macro} :#{name}"),
+          facts(primary),
+          *Docstring.new(context, primary, @from).render(documented(accessors).docstring)
+        ]
+      end
+
+      # @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}"
+      end
+
+      private
+
+      def documented(accessors)
+        accessors.find { |meth| !meth.docstring.empty? } || accessors.first
+      end
+
+      # Explicit anchors, because heading slugs cannot tell `foo`, `foo?`, and `foo!` apart.
+      def heading(title, objects)
+        anchors = objects.map { |object| %(<a id="#{path_map.anchor_for(object)}"></a>) }.join
+        "### #{anchors}#{code(title)}"
+      end
+
+      def facts(meth)
+        lines = []
+        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.join("\n") unless lines.empty?
+      end
+
+      def alias_link(meth)
+        original = registry[Model::MethodObject.path_for(meth.namespace, meth.scope, meth.alias_for)]
+        label = code("#{meth.separator}#{meth.alias_for}")
+        original ? linker.link(original, from: @from, label: label) : label
+      end
+
+      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)) }
+      end
+    end
+  end
+end

data/lib/boondoc/renderer/namespace_page.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+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
+      MAX_CONSTANT_LINES = 12
+      # A guard against a superclass chain that never ends; real chains are far shorter.
+      MAX_SUPERCLASS_CHAIN = 20
+
+      # @param context [Context]
+      # @param namespace [Model::NamespaceObject]
+      def initialize(context, namespace)
+        super(context)
+        @namespace = namespace
+        @from = path_map.file_for(namespace)
+        @methods = MethodSection.new(context, @from)
+      end
+
+      # @return [Boolean] false when there is nothing worth writing a page for
+      def content?
+        !@namespace.root? || visible(@namespace.children.grep_v(Model::NamespaceObject)).any?
+      end
+
+      # @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
+                 ])
+      end
+
+      private
+
+      def visible(objects)
+        objects.select { |object| filter.visible?(object) }
+      end
+
+      def title
+        return 'Top level' if @namespace.root?
+
+        "#{@namespace.kind.to_s.capitalize}: #{@namespace.path}"
+      end
+
+      # --- header -------------------------------------------------------------
+
+      def facts
+        lines = []
+        lines << "- **Inherits:** #{superclass_chain.join(' < ')}" if @namespace.superclass
+        lines.concat(mixin_facts)
+        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?
+        end
+      end
+
+      def constant_link(name)
+        found = registry.resolve(@namespace, name)
+        found.is_a?(Model::NamespaceObject) ? linker.link(found, from: @from) : code(name)
+      end
+
+      def superclass_chain
+        chain = []
+        current = @namespace
+        while current&.superclass && chain.size < MAX_SUPERCLASS_CHAIN
+          found = registry.superclass(current)
+          chain << (found ? linker.link(found, from: @from) : code(current.superclass))
+          current = found
+          break if current.equal?(@namespace)
+        end
+        chain
+      end
+
+      def source_links
+        @namespace.files.map { |file, _| "[#{code(file)}](#{path_map.source_href(file, from: @from)})" }
+      end
+
+      # --- sections -----------------------------------------------------------
+
+      def namespaces
+        children = visible(@namespace.namespaces)
+        return nil if children.empty?
+
+        ['## 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) }]
+      end
+
+      def constant_section(constant)
+        [
+          %(### <a id="#{path_map.anchor_for(constant)}"></a>#{code(constant.name)}),
+          ruby("#{constant.name} = #{truncate(constant.value)}"),
+          *Docstring.new(context, constant, @from).render(constant.docstring)
+        ]
+      end
+
+      def truncate(value)
+        lines = value.lines
+        return value if lines.size <= MAX_CONSTANT_LINES
+
+        "#{lines.first(MAX_CONSTANT_LINES).join.rstrip}\n# ... (#{lines.size - MAX_CONSTANT_LINES} more lines)"
+      end
+
+      def attributes
+        groups = SCOPES.keys.flat_map do |scope|
+          visible(context.meths(@namespace, scope)).select(&:attribute)
+                                                   .group_by { |meth| meth.name.delete_suffix('=') }.values
+        end
+        return nil if groups.empty?
+
+        ['## Attributes', *groups.flat_map { |accessors| @methods.render_attribute(accessors) }]
+      end
+
+      def method_sections(scope)
+        meths = visible(context.meths(@namespace, scope)).reject(&:attribute)
+        return nil if meths.empty?
+
+        ["## #{SCOPES[scope]}", summary_table(meths), *meths.flat_map { |meth| @methods.render(meth) }]
+      end
+
+      def summary_table(meths)
+        rows = meths.map do |meth|
+          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")
+      end
+
+      # Each method is listed under the nearest ancestor that defines it, the
+      # one Ruby would actually call.
+      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?
+      end
+
+      def inherited_from_ancestor(ancestor, seen)
+        meths = context.meths(ancestor, :instance).reject { |meth| seen.include?(meth.name) }
+        seen.merge(meths.map(&:name))
+        inherited_from(ancestor, visible(meths)) if filter.visible?(ancestor)
+      end
+
+      def inherited_from(ancestor, meths)
+        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(', ')}"
+      end
+    end
+  end
+end