refactor RDoc markup handling for improved loading and initialization

Author: seuros

lib/yard/templates/helpers/markup/rdoc_markdown.rb

@@ -3,8 +3,8 @@ module YARD
   module Templates
     module Helpers
       module Markup
-        begin require 'rdoc'; rescue LoadError; nil end
         begin
+          require 'rdoc'
           require 'rdoc/markdown'
         rescue LoadError
           raise NameError, "could not load RDoc Markdown support (rdoc is too old)"

lib/yard/templates/helpers/markup/rdoc_markup.rb

@@ -1,68 +1,56 @@
 # frozen_string_literal: true
 require 'thread'
 
+gem 'rdoc', '>= 6.0'
+require 'rdoc'
+require 'rdoc/markup'
+require 'rdoc/markup/to_html'
+
 module YARD
   module Templates
     module Helpers
       module Markup
-        begin require 'rdoc'; rescue LoadError; nil end
-        begin
-          require 'rdoc/markup'
-          require 'rdoc/markup/to_html'
-          class RDocMarkup; MARKUP = RDoc::Markup end
-          class RDocMarkupToHtml < RDoc::Markup::ToHtml
-            if defined?(RDoc::VERSION) && RDoc::VERSION >= '4.0.0' &&
-               defined?(RDoc::Options)
-              def initialize
-                options = RDoc::Options.new
-                options.pipe = true
-                super(options)
-              end
-            end
-          end
-        rescue LoadError
-          begin
-            require 'rdoc/markup/simple_markup'
-            require 'rdoc/markup/simple_markup/to_html'
-            class RDocMarkup; MARKUP = SM::SimpleMarkup end
-            class RDocMarkupToHtml < SM::ToHtml; end
-          rescue LoadError
-            raise NameError, "could not load RDocMarkup (rdoc is not installed)"
-          end
-        end
-
         class RDocMarkup
+          MARKUP = RDoc::Markup
+
           attr_accessor :from_path
 
-          @@mutex = Mutex.new
-          @@formatter = nil
-          @@markup = nil
+          # Class instance variables initialized once
+          @mutex = Mutex.new
+          @formatter = nil
+          @markup = nil
 
-          def initialize(text)
-            @text = text
+          class << self
+            attr_reader :mutex, :formatter, :markup
+
+            def initialize_markup_components
+              return if @markup && @formatter
 
-            @@mutex.synchronize do
-              @@formatter ||= RDocMarkupToHtml.new
-              @@markup ||= MARKUP.new
+              @mutex.synchronize do
+                @formatter ||= RDocMarkupToHtml.new
+                @markup ||= MARKUP.new
+              end
             end
           end
 
+          def initialize(text)
+            @text = text
+            self.class.initialize_markup_components
+          end
+
           def to_html
             html = nil
-            @@mutex.synchronize do
-              @@formatter.from_path = from_path
-              html = @@markup.convert(@text, @@formatter)
+            self.class.mutex.synchronize do
+              self.class.formatter.from_path = from_path
+              html = self.class.markup.convert(@text, self.class.formatter)
             end
-            html = fix_dash_dash(html)
-            html = fix_typewriter(html)
-            html
+
+            fix_dash_dash(fix_typewriter(html))
           end
 
           private
 
           # Fixes RDoc behaviour with ++ only supporting alphanumeric text.
-          #
-          # @todo Refactor into own SimpleMarkup subclass
           def fix_typewriter(text)
             code_tags = 0
             text.gsub(%r{<(/)?(pre|code|tt)|(\s|^|>)\+(?! )([^\n\+]{1,900})(?! )\+}) do |str|
@@ -76,33 +64,66 @@ def fix_typewriter(text)
                 next str
               end
               next str unless code_tags == 0
-              first_text + '<tt>' + type_text + '</tt>'
+              "#{first_text}<tt>#{type_text}</tt>"
             end
           end
 
-          # Don't allow -- to turn into &#8212; element. The chances of this being
-          # some --option is far more likely than the typographical meaning.
-          #
-          # @todo Refactor into own SimpleMarkup subclass
+          # Don't allow -- to turn into &#8212; element (em dash)
           def fix_dash_dash(text)
             text.gsub(/&#8212;(?=\S)/, '--')
           end
         end
 
-        class RDocMarkupToHtml
+        # Specialized ToHtml formatter for YARD
+        class RDocMarkupToHtml < RDoc::Markup::ToHtml
           attr_accessor :from_path
 
+          def initialize
+            options = RDoc::Options.new
+            options.pipe = true
+            super(options)
+
+            # The hyperlink detection state
+            @hyperlink = false
+          end
+
           # Disable auto-link of URLs
-          def handle_special_HYPERLINK(special) # rubocop:disable Style/MethodName
+          def handle_special_HYPERLINK(special)
             @hyperlink ? special.text : super
           end
 
           def accept_paragraph(*args)
             par = args.last
             text = par.respond_to?(:txt) ? par.txt : par.text
-            @hyperlink = text =~ /\{(https?:|mailto:|link:|www\.)/ ? true : false
+            @hyperlink = text =~ /\{(https?:|mailto:|link:|www\.)/
             super
           end
+
+          # Override gen_url to support from_path in relative links
+          def gen_url(url, text)
+            scheme, path, id = parse_url(url)
+
+            if scheme == 'link' && !path.start_with?('/') && !from_path.nil? && !from_path.empty?
+              # Make the path relative to from_path for link: URLs
+              path = File.expand_path(path, File.dirname(from_path))
+            end
+
+            super("#{scheme}:#{path}#{id}", text)
+          end
+
+          # Override parse_url to handle custom schemes
+          def parse_url(url)
+            case url
+            when /^mailto:(.*)$/i
+              ['mailto', $1, '']
+            when /^(https?|ftp|irc):(.*)$/i
+              [$1, $2, '']
+            when /^link:(.*)$/i
+              ['link', $1, '']
+            else
+              ['http', url, '']
+            end
+          end
         end
       end
     end