Merge pull request #856 from realm/jf-autolink-fixes

Fixes to autolinking

CHANGELOG.md

@@ -15,6 +15,13 @@
   [JP Simard](https://github.com/jpsim)
   [#860](https://github.com/realm/jazzy/issues/860)
 
+* Autolink from parameter documentation and from external markdown documents
+  including README.  Autolink to symbols containing & < >.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#715](https://github.com/realm/jazzy/issues/715)
+  [#789](https://github.com/realm/jazzy/issues/789)
+  [#805](https://github.com/realm/jazzy/issues/805)
+
 ## 0.8.3
 
 ##### Breaking

lib/jazzy/doc_builder.rb

@@ -208,6 +208,11 @@ def self.copy_assets(destination)
       end
     end
 
+    def self.render(doc_model, markdown)
+      html = Markdown.render(markdown)
+      SourceKitten.autolink_document(html, doc_model)
+    end
+
     # Build Mustache document from a markdown source file
     # @param [Config] options Build options
     # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
@@ -218,7 +223,7 @@ def self.document_markdown(source_module, doc_model, path_to_root)
       doc = Doc.new # Mustache model instance
       name = doc_model.name == 'index' ? source_module.name : doc_model.name
       doc[:name] = name
-      doc[:overview] = Markdown.render(doc_model.content(source_module))
+      doc[:overview] = render(doc_model, doc_model.content(source_module))
       doc[:custom_head] = Config.instance.custom_head
       doc[:disable_search] = Config.instance.disable_search
       doc[:doc_coverage] = source_module.doc_coverage unless
@@ -230,7 +235,7 @@ def self.document_markdown(source_module, doc_model, path_to_root)
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:hide_name] = true
-      doc.render
+      doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
     end
 
     # Returns the appropriate color for the provided percentage,
@@ -365,7 +370,7 @@ def self.document(source_module, doc_model, path_to_root)
       overview = (doc_model.abstract || '') + (doc_model.discussion || '')
       alternative_abstract = doc_model.alternative_abstract
       if alternative_abstract
-        overview = Markdown.render(alternative_abstract) + overview
+        overview = render(doc_model, alternative_abstract) + overview
       end
 
       doc = Doc.new # Mustache model instance

lib/jazzy/sourcekitten.rb

@@ -2,6 +2,7 @@
 require 'pathname'
 require 'shellwords'
 require 'xcinvoke'
+require 'CGI'
 
 require 'jazzy/config'
 require 'jazzy/executable'
@@ -27,7 +28,7 @@ def autolink_block(doc_url, middle_regex, after_highlight)
     gsub(autolink_regex(middle_regex, after_highlight)) do
       original = Regexp.last_match(0)
       start_tag, raw_name, end_tag = Regexp.last_match.captures
-      link_target = yield(raw_name)
+      link_target = yield(CGI.unescape_html(raw_name))
 
       if link_target &&
          !link_target.type.extension? &&
@@ -294,7 +295,7 @@ def self.parameters(doc, discovered)
           name: name,
           discussion: discovered[name],
         }
-      end
+      end.reject { |param| param[:discussion].nil? }
     end
 
     # rubocop:disable Metrics/CyclomaticComplexity
@@ -540,7 +541,7 @@ def self.name_match(name_part, docs)
       return nil unless name_part
       wildcard_expansion = Regexp.escape(name_part)
                                  .gsub('\.\.\.', '[^)]*')
-                                 .gsub(/<.*>/, '')
+                                 .gsub(/<.*>/, '')
       whole_name_pat = /\A#{wildcard_expansion}\Z/
       docs.find do |doc|
         whole_name_pat =~ doc.name
@@ -602,11 +603,16 @@ def self.autolink_text(text, doc, root_decls, after_highlight = false)
     end
 
     def self.autolink(docs, root_decls)
+      @autolink_root_decls = root_decls
       docs.each do |doc|
         doc.children = autolink(doc.children, root_decls)
 
         doc.return = autolink_text(doc.return, doc, root_decls) if doc.return
         doc.abstract = autolink_text(doc.abstract, doc, root_decls)
+        (doc.parameters || []).each do |param|
+          param[:discussion] =
+            autolink_text(param[:discussion], doc, root_decls)
+        end
 
         if doc.declaration
           doc.declaration = autolink_text(
@@ -622,6 +628,11 @@ def self.autolink(docs, root_decls)
       end
     end
 
+    # For autolinking external markdown documents
+    def self.autolink_document(html, doc)
+      autolink_text(html, doc, @autolink_root_decls || [])
+    end
+
     def self.reject_objc_types(docs)
       enums = docs.map do |doc|
         [doc, doc.children]