zard-doc 0.0.1 → 0.0.2

data/lib/zard/doc/reference_markup.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Zard
+  module Doc
+    class ReferenceMarkup
+      HTML_OR_AUTOLINK = /\A<(?:[A-Za-z][A-Za-z0-9+.-]{1,31}:[^<>\s]*|[^<>\s]+@[^<>\s]+|\/[A-Za-z][A-Za-z0-9-]*\s*|[A-Za-z][A-Za-z0-9-]*(?:\s+[A-Za-z_:][A-Za-z0-9_.:-]*(?:\s*=\s*(?:[^\s"'=<>`]+|'[^']*'|"[^"]*"))?)*\s*\/?|!--.*?--|![A-Z]+(?:\s+[^<>]*)?|\?.*?\?)>/m
+
+      def self.rewrite(text, &reference)
+        new(reference).rewrite(text)
+      end
+
+      def self.code_label?(text)
+        text.start_with?("`") && code_end(text, 0) == text.length
+      end
+
+      def self.code_end(text, position)
+        delimiter = text[position..].match(/\A`+/)[0]
+        closing = text.match(/(?<!`)#{Regexp.escape(delimiter)}(?!`)/, position + delimiter.length)
+        closing&.end(0)
+      end
+
+      def initialize(reference)
+        @reference = reference
+      end
+
+      def rewrite(text)
+        segments = []
+        prose = +""
+        fence = nil
+        definition = false
+        definition_destination = false
+        definition_title = nil
+        list_indentations = []
+        previous_quotes = 0
+        @reference_labels = {}
+        text.each_line do |line|
+          if fence
+            content = fence_content(line, fence)
+            if content
+              segments << [false, line]
+              delimiter = fence[:delimiter]
+              closing = content.match(/\A {0,3}(`{3,}|~{3,})([^\n]*)/)
+              fence = nil if closing && closing[1][0] == delimiter[0] && closing[1].length >= delimiter.length && closing[2].strip.empty?
+              next
+            end
+            fence = nil
+          end
+          if definition_title
+            segments << [false, line]
+            definition_title = nil if title_end(line, definition_title) || line.strip.empty?
+            next
+          end
+          prefix = line[/\A(?: {0,3}(?:> ?|(?:[-+*]|\d+[.)])(?: {1,4}(?! )| (?= {4})|\t)))+/].to_s
+          content = line.delete_prefix(prefix)
+          quotes = prefix.count(">")
+          quote_content = line.sub(/\A(?: {0,3}> ?)+/, "")
+          indentation = columns(quote_content[/\A[ \t]*/])
+          list_start = prefix.match?(/[-+*]|\d+[.)]/)
+          list_indentations.clear if quotes != previous_quotes
+          if list_start
+            list_indentations.pop while list_indentations.last && list_indentations.last > indentation
+            list_indentations << columns(prefix.gsub(/ {0,3}> ?/, ""))
+          elsif !line.strip.empty?
+            list_indentations.pop while list_indentations.last && list_indentations.last > indentation
+          end
+          list_indentation = list_indentations.last
+          content = dedent(quote_content, list_indentation) if !list_start && list_indentation
+          setext = content.match?(/\A {0,3}(?:=+|-+)[ \t]*\r?\n?\z/)
+          block_start = setext || list_start || quotes != previous_quotes || content.match?(/\A {0,3}(?:\#{1,6}(?:[ \t]|$)|(?:[-*_][ \t]*){3,}$)/)
+          if block_start
+            segments << [true, prose.dup]
+            prose.clear
+          end
+          previous_quotes = quotes
+          marker = content.match(/\A {0,3}(`{3,}|~{3,})([^\n]*)/)
+          code_indentation = list_start ? columns(content[/\A[ \t]*/]) : indentation - (list_indentation || 0)
+          indented = code_indentation >= 4 && prose.empty?
+          reference_definition = content.match(/\A {0,3}\[([^\n]+)\]:/)
+          if (definition && (definition_destination || content.match?(/\A[ \t]+\S/) || content.match?(/\A {0,3}["'(]/))) || reference_definition || line.strip.empty? || indented || (marker && (marker[1][0] != "`" || !marker[2].include?("`")))
+            segments << [true, prose.dup]
+            prose.clear
+            segments << [false, line]
+            definition = !!reference_definition || (definition && !line.strip.empty?)
+            definition_destination = !!(reference_definition && content[reference_definition.end(0)..].strip.empty?)
+            definition_title = open_title(reference_definition ? content[reference_definition.end(0)..] : content) if definition
+            @reference_labels[normalize_label(reference_definition[1])] = true if reference_definition
+            if marker
+              fence = {delimiter: marker[1], quotes: quotes, indentation: list_indentation}
+            end
+          else
+            definition = false
+            definition_destination = false
+            prose << line
+          end
+          if setext || content.match?(/\A {0,3}\#{1,6}(?:[ \t]|$)/)
+            segments << [true, prose.dup]
+            prose.clear
+          end
+        end
+        segments << [true, prose]
+        segments.map { |rewrite, source| rewrite ? rewrite_inline(source) : source }.join
+      end
+
+      private
+
+      def rewrite_inline(text)
+        output = +""
+        position = 0
+        while position < text.length
+          if text[position] == "\\"
+            output << text[position, 2]
+            position += 2
+          elsif text[position] == "`"
+            ending = self.class.code_end(text, position) || (position + text[position..].match(/\A`+/)[0].length)
+            output << text[position...ending]
+            position = ending
+          elsif text[position] == "!" && text[position + 1] == "[" && (ending = bracket_end(text, position + 1))
+            ending = link_end(text, ending) || ending
+            output << text[position...ending]
+            position = ending
+          elsif text[position] == "[" && (ending = bracket_end(text, position))
+            body = text[(position + 1)...(ending - 1)]
+            if (link_ending = link_end(text, ending))
+              destination = text[(ending + 1)...(link_ending - 1)]
+              value = (text[ending] == "(") ? destination.match(/\A([mc]):([^\s]+)\z/) : nil
+              replacement = value && @reference.call(value[1], decode(value[2]), body)
+              output << (replacement || text[position...link_ending])
+              position = link_ending
+            else
+              if @reference_labels.key?(normalize_label(body))
+                output << text[position...ending]
+                position = ending
+                next
+              end
+              rd = body.start_with?("[") && body.end_with?("]")
+              body = body[1...-1].strip if rd
+              value = body.match(/\A([mc]):([^\s]+)\z/)
+              if value
+                target = decode(value[2])
+                output << (@reference.call(value[1], target, nil) || text[position...ending])
+                position = ending
+              elsif rd
+                output << text[position...ending]
+                position = ending
+              else
+                output << text[position]
+                position += 1
+              end
+            end
+          elsif text[position, 2] == "[["
+            output << "[["
+            position += 2
+          elsif text[position] == "<" && (html = text[position..].match(HTML_OR_AUTOLINK))
+            output << html[0]
+            position += html[0].length
+          else
+            output << text[position]
+            position += 1
+          end
+        end
+        output
+      end
+
+      def decode(target)
+        target.gsub(/\\([\\\[\]])/, '\1')
+      end
+
+      def columns(text)
+        text.each_char.reduce(0) { |column, character| (character == "\t") ? column + 4 - column % 4 : column + 1 }
+      end
+
+      def dedent(text, indentation)
+        whitespace = text[/\A[ \t]*/]
+        " " * [columns(whitespace) - indentation, 0].max + text.delete_prefix(whitespace)
+      end
+
+      def open_title(text)
+        opening = text.match(/(?:\A|[ \t])(["'(])/)
+        return unless opening
+
+        delimiter = (opening[1] == "(") ? ")" : opening[1]
+        delimiter unless title_end(text[opening.end(0)..], delimiter)
+      end
+
+      def title_end(text, delimiter)
+        position = 0
+        while position < text.length
+          return position + 1 if text[position] == delimiter
+
+          position += (text[position] == "\\") ? 2 : 1
+        end
+        nil
+      end
+
+      def fence_content(line, fence)
+        content = line
+        fence[:quotes].times do
+          quote = content[/\A {0,3}> ?/]
+          return unless quote
+
+          content = content.delete_prefix(quote)
+        end
+        indentation = fence[:indentation]
+        return content unless indentation
+        return if !content.strip.empty? && columns(content[/\A[ \t]*/]) < indentation
+
+        dedent(content, indentation)
+      end
+
+      def normalize_label(label)
+        label.strip.gsub(/\s+/, " ").downcase
+      end
+
+      def bracket_end(text, position)
+        depth = 0
+        while position < text.length
+          case text[position]
+          when "\\"
+            position += 2
+            next
+          when "`"
+            ending = self.class.code_end(text, position) || (position + text[position..].match(/\A`+/)[0].length)
+            position = ending
+            next
+          when "["
+            depth += 1
+          when "]"
+            depth -= 1
+            return position + 1 if depth.zero?
+          end
+          position += 1
+        end
+        nil
+      end
+
+      def link_end(text, position)
+        return bracket_end(text, position) if text[position] == "["
+        return unless text[position] == "("
+
+        depth = 0
+        quote = nil
+        angle = false
+        while position < text.length
+          if text[position] == "\\"
+            position += 2
+            next
+          end
+          if quote
+            quote = nil if text[position] == quote
+          elsif angle
+            angle = false if text[position] == ">"
+          elsif ["\"", "'"].include?(text[position]) && text[position - 1].match?(/\s/)
+            quote = text[position]
+          elsif text[position] == "<"
+            angle = true
+          else
+            case text[position]
+            when "("
+              depth += 1
+            when ")"
+              depth -= 1
+              return position + 1 if depth.zero?
+            end
+          end
+          position += 1
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/zard/doc/renderer.rb

@@ -4,77 +4,107 @@ module Zard
   module Doc
     class Renderer
       def self.render(document)
-        new(document).render
+        new([document]).render
       end
 
-      def initialize(document)
-        @document = document
+      def self.render_documents(documents)
+        new(documents).render
       end
 
-      def render
-        sections = @document.declarations.filter_map { |declaration| render_declaration(declaration) }
-        return "" if sections.empty?
+      def initialize(documents)
+        @documents = documents
+        @container_names = documents.flat_map(&:declarations).select { |declaration| %i[class module constant].include?(declaration.kind) }.map { |declaration| qualified_name(declaration) }
+        @targets = Hash.new { |hash, key| hash[key] = [] }
+        documents.flat_map(&:declarations).each do |declaration|
+          reference_names(declaration).each { |name| @targets[name] << declaration }
+        end
+        @anchors = {}
+        @descriptions = {}
+        @text = {}
+        documents.flat_map(&:declarations).each do |declaration|
+          next unless renderable?(declaration)
+
+          text = declaration.documentation.select { |tag| tag.name == :text }.map(&:description).join("\n")
+          @text[declaration] = render_prose(text, declaration)
+          @descriptions[declaration] = declaration.documentation.to_h do |tag|
+            description = case tag.name
+            when :example, :raw, :text
+              tag.description
+            when :see
+              render_reference(tag.description, declaration)
+            else
+              render_prose(tag.description, declaration)
+            end
+            [tag, description]
+          end
+        end
+      end
 
-        "#{sections.join("\n\n")}\n"
+      def render
+        @documents.filter_map do |document|
+          sections = document.declarations.filter_map { |declaration| render_declaration(declaration) }
+          "#{sections.join("\n\n")}\n" unless sections.empty?
+        end.join("\n")
       end
 
       private
 
       def render_declaration(declaration)
-        return unless declaration.visibility == :public
+        return unless renderable?(declaration)
 
         documentation = declaration.documentation.reject { |tag| tag.name == :raw }
-        return if documentation.empty?
+        description = ->(tag) { @descriptions.fetch(declaration).fetch(tag) }
 
         parts = [heading(declaration)]
+        parts.unshift("<a id=\"#{@anchors[declaration]}\"></a>") if @anchors.key?(declaration)
         parts << "Superclass: `#{declaration.superclass}`." if declaration.superclass
         parts << render_container_builder(declaration) if declaration.container_builder
         append_mixins(parts, declaration)
         parts << "Alias of `#{display_alias_target(declaration)}`." if declaration.alias_target
-        text = documentation.select { |tag| tag.name == :text }.map(&:description)
-        parts << text.join("\n") unless text.empty?
+        text = @text.fetch(declaration)
+        parts << text unless text.empty?
 
         deprecated = documentation.select { |tag| tag.name == :deprecated }
-        parts << "### Deprecated\n\n#{deprecated.map(&:description).join("\n\n")}" unless deprecated.empty?
+        parts << "### Deprecated\n\n#{deprecated.map(&description).join("\n\n")}" unless deprecated.empty?
 
         notes = documentation.select { |tag| tag.name == :note }
-        parts << "### Notes\n\n#{notes.map(&:description).join("\n\n")}" unless notes.empty?
+        parts << "### Notes\n\n#{notes.map(&description).join("\n\n")}" unless notes.empty?
 
         examples = documentation.select { |tag| tag.name == :example }
-        parts << "### Examples\n\n#{examples.map(&:description).join("\n\n")}" unless examples.empty?
+        parts << "### Examples\n\n#{examples.map(&description).join("\n\n")}" unless examples.empty?
 
         parameters = documentation.select { |tag| tag.name == :param }
         unless parameters.empty?
-          items = parameters.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          items = parameters.map { |tag| list_item("`#{tag.subject}` — ", description.call(tag)) }
           parts << "### Parameters\n\n#{items.join("\n")}"
         end
 
         returns = documentation.select { |tag| tag.name == :return }
-        parts << "### Returns\n\n#{returns.map(&:description).join("\n\n")}" unless returns.empty?
+        parts << "### Returns\n\n#{returns.map(&description).join("\n\n")}" unless returns.empty?
 
         documentation.select { |tag| tag.name == :option }.group_by(&:owner).each do |owner, options|
-          items = options.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          items = options.map { |tag| list_item("`#{tag.subject}` — ", description.call(tag)) }
           parts << "### Options for `#{owner}`\n\n#{items.join("\n")}"
         end
 
         raises = documentation.select { |tag| tag.name == :raise }
         unless raises.empty?
-          items = raises.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          items = raises.map { |tag| list_item("`#{tag.subject}` — ", description.call(tag)) }
           parts << "### Raises\n\n#{items.join("\n")}"
         end
 
         yield_parameters = documentation.select { |tag| tag.name == :yieldparam }
         unless yield_parameters.empty?
-          items = yield_parameters.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          items = yield_parameters.map { |tag| list_item("`#{tag.subject}` — ", description.call(tag)) }
           parts << "### Yield parameters\n\n#{items.join("\n")}"
         end
 
         yield_returns = documentation.select { |tag| tag.name == :yieldreturn }
-        parts << "### Yields\n\n#{yield_returns.map(&:description).join("\n\n")}" unless yield_returns.empty?
+        parts << "### Yields\n\n#{yield_returns.map(&description).join("\n\n")}" unless yield_returns.empty?
 
         see_also = documentation.select { |tag| tag.name == :see }
         unless see_also.empty?
-          items = see_also.map { |tag| list_item("", tag.description) }
+          items = see_also.map { |tag| list_item("", description.call(tag)) }
           parts << "### See also\n\n#{items.join("\n")}"
         end
         parts.join("\n\n")
@@ -133,6 +163,115 @@ module Zard
         [declaration.namespace, declaration.name].compact.join("::")
       end
 
+      def renderable?(declaration)
+        declaration.visibility == :public && declaration.documentation.any? { |tag| tag.name != :raw }
+      end
+
+      def reference_names(declaration)
+        return [] if declaration.refinement || declaration.kind == :refinement
+        return [qualified_name(declaration)] if %i[class module constant].include?(declaration.kind)
+
+        singleton = declaration.kind.to_s.start_with?("singleton_")
+        owner = singleton ? reference_owner(declaration) : declaration.namespace
+        return [] if singleton && !owner && declaration.namespace
+        return [] if owner && !owner.match?(/\A(?:::)?[[:upper:]\p{Lt}][[:word:]]*(?:::[[:upper:]\p{Lt}][[:word:]]*)*\z/)
+
+        name = "#{owner&.delete_prefix("::")}#{singleton ? "." : "#"}#{declaration.name}"
+        name += "=" if declaration.kind.to_s.end_with?("attribute_writer")
+        declaration.kind.to_s.end_with?("attribute_accessor") ? [name, "#{name}="] : [name]
+      end
+
+      def resolve_reference(reference, declaration)
+        return unless reference && !declaration.refinement
+
+        path = reference.sub(/\A((?:::)?[[:upper:]\p{Lt}][[:word:]]*(?:::[[:upper:]\p{Lt}][[:word:]]*)*)?(?:\?\.|\.#)/) { "#{$1}." }
+        if path.start_with?("::")
+          candidates = [path.delete_prefix("::")]
+        elsif path.start_with?("#", ".")
+          owner = declaration.kind.to_s.start_with?("singleton_") ? reference_owner(declaration) : declaration.namespace
+          owner = qualified_name(declaration) if %i[class module].include?(declaration.kind)
+          candidates = ["#{owner&.delete_prefix("::")}#{path}"]
+        else
+          namespace = declaration.namespace
+          namespace = qualified_name(declaration) if %i[class module].include?(declaration.kind)
+          candidates = lexical_candidates(path, namespace)
+        end
+        candidates.each do |candidate|
+          targets = @targets[candidate].uniq
+          if targets.empty?
+            first_constant = path.split(/::|[.#]/).first.to_s
+            local_constant = "#{candidate.delete_suffix(path)}#{first_constant}"
+            return nil if !first_constant.empty? && @container_names.include?(local_constant)
+
+            next
+          end
+
+          return targets.first if targets.length == 1 && renderable?(targets.first)
+
+          return nil
+        end
+        nil
+      end
+
+      def lexical_candidates(path, namespace)
+        parts = namespace.to_s.split("::")
+        parts.length.downto(0).map { |length| [*parts.first(length), path].join("::") }
+      end
+
+      def reference_owner(declaration)
+        owner = singleton_owner(declaration)
+        return owner unless owner && declaration.receiver && declaration.receiver != "self"
+        return owner.delete_prefix("::") if owner.start_with?("::")
+        return owner unless declaration.namespace
+
+        lexical_candidates(owner, declaration.namespace).find { |candidate| @container_names.include?(candidate) }
+      end
+
+      def anchor(declaration)
+        "zard-#{reference_names(declaration).first.bytes.map { |byte| byte.to_s(16).rjust(2, "0") }.join}"
+      end
+
+      def render_reference(description, declaration)
+        explicit = false
+        prose = render_prose(description, declaration) { explicit = true }
+        return prose if explicit
+
+        reference, label = description.strip.split(/\s+/, 2)
+        return description unless reference
+
+        destination = if reference.match?(/\A(?:https?:\/\/|mailto:)/)
+          reference.gsub(/[\\()< >]/) { |character| "%%%02X" % character.ord }.gsub("&", "&amp;")
+        elsif (target = resolve_reference(reference, declaration))
+          "##{@anchors[target] ||= anchor(target)}"
+        end
+        return description unless destination
+
+        title = escape_label(label || reference)
+        "[#{title}](#{destination})"
+      end
+
+      def render_prose(description, declaration)
+        ReferenceMarkup.rewrite(description) do |scheme, reference, label|
+          yield if block_given?
+          target = resolve_reference(reference, declaration)
+          next unless target
+          container = %i[class module].include?(target.kind)
+          next if (scheme == "c") != container
+
+          destination = @anchors[target] ||= anchor(target)
+          title = label || reference
+          unless label && ReferenceMarkup.code_label?(label)
+            title = title.gsub(/\\([\\\[\]])/, '\1') if label
+            title = escape_label(title)
+          end
+          "[#{title}](##{destination})"
+        end
+      end
+
+      def escape_label(label)
+        label.gsub(/[&<>]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;").gsub(/[\\\[\]`*_~]/) { |character| "\\#{character}" }
+      end
+
       def display_name(declaration)
         if declaration.refinement
           separator = declaration.kind.to_s.start_with?("singleton_") ? "." : "#"

data/lib/zard/doc/version.rb

@@ -2,6 +2,6 @@
 
 module Zard
   module Doc
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

data/lib/zard/doc.rb

@@ -2,6 +2,7 @@
 
 require "zard"
 require_relative "doc/version"
+require_relative "doc/reference_markup"
 require_relative "doc/renderer"
 
 module Zard
@@ -10,6 +11,6 @@ module Zard
       Renderer.render(document)
     end
 
-    private_constant :Renderer
+    private_constant :Renderer, :ReferenceMarkup
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zard-doc
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - USAMI Kenta
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.1
+        version: 0.0.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.1
+        version: 0.0.2
 description: zard-doc renders API documentation from the versioned ZARD document model.
 email:
 - tadsan@zonu.me
@@ -35,7 +35,13 @@ files:
 - README.md
 - exe/zard-doc
 - lib/zard/doc.rb
+- lib/zard/doc/build.rb
+- lib/zard/doc/build_configuration.rb
+- lib/zard/doc/build_export.rb
+- lib/zard/doc/build_publisher.rb
+- lib/zard/doc/build_renderer.rb
 - lib/zard/doc/cli.rb
+- lib/zard/doc/reference_markup.rb
 - lib/zard/doc/renderer.rb
 - lib/zard/doc/version.rb
 homepage: https://github.com/rigortype/zard
@@ -60,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Markdown API documentation for ZARD
 test_files: []