jazzy 0.13.4 → 0.14.0

data/lib/jazzy/source_declaration.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 require 'jazzy/source_declaration/access_control_level'
 require 'jazzy/source_declaration/type'
 
-# rubocop:disable Metrics/ClassLength
 module Jazzy
+  # rubocop:disable Metrics/ClassLength
   class SourceDeclaration
     # kind of declaration (e.g. class, variable, function)
     attr_accessor :type
@@ -11,7 +13,9 @@ module Jazzy
 
     # Give the item its own page or just inline into parent?
     def render_as_page?
-      children.any?
+      children.any? ||
+        (Config.instance.separate_global_declarations &&
+         type.global?)
     end
 
     def swift?
@@ -25,7 +29,8 @@ module Jazzy
     # When referencing this item from its parent category,
     # include the content or just link to it directly?
     def omit_content_from_parent?
-      false
+      Config.instance.separate_global_declarations &&
+        render_as_page?
     end
 
     # Element containing this declaration in the code
@@ -36,7 +41,7 @@ module Jazzy
     attr_accessor :parent_in_docs
 
     # counterpart of parent_in_docs
-    attr_accessor :children
+    attr_reader :children
 
     def children=(new_children)
       # Freeze to ensure that parent_in_docs stays in sync
@@ -73,7 +78,7 @@ module Jazzy
     # of the extended objc class and the category name itself, i.e.
     # ["NSString", "MyMethods"], nil otherwise.
     def objc_category_name
-      name.split(/[\(\)]/) if type.objc_category?
+      name.split(/[()]/) if type.objc_category?
     end
 
     def swift_objc_extension?
@@ -108,6 +113,7 @@ module Jazzy
     attr_accessor :line
     attr_accessor :column
     attr_accessor :usr
+    attr_accessor :type_usr
     attr_accessor :modulename
     attr_accessor :name
     attr_accessor :objc_name
@@ -141,6 +147,16 @@ module Jazzy
       CGI.unescape(url)
     end
 
+    # Base filename (no extension) for the item
+    def docs_filename
+      result = url_name || name
+      # Workaround functions sharing names with
+      # different argument types (f(a:Int) vs. f(a:String))
+      return result unless type.swift_global_function?
+
+      result + "_#{type_usr}"
+    end
+
     def constrained_extension?
       type.swift_extension? &&
         generic_requirements
@@ -162,6 +178,7 @@ module Jazzy
     # Is there at least one inherited type that is not in the given list?
     def other_inherited_types?(unwanted)
       return false unless inherited_types?
+
       inherited_types.any? { |t| !unwanted.include?(t) }
     end
 
@@ -188,7 +205,9 @@ module Jazzy
       return [] unless
         Config.instance.abstract_glob_configured &&
         Config.instance.abstract_glob
+
       Config.instance.abstract_glob.select { |e| File.file? e }
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/jazzy/source_declaration/access_control_level.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
   class SourceDeclaration
     class AccessControlLevel
@@ -5,12 +7,12 @@ module Jazzy
 
       attr_reader :level
 
-      ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'.freeze
+      ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'
       ACCESSIBILITY_FILEPRIVATE =
-        'source.lang.swift.accessibility.fileprivate'.freeze
-      ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'.freeze
-      ACCESSIBILITY_PUBLIC = 'source.lang.swift.accessibility.public'.freeze
-      ACCESSIBILITY_OPEN = 'source.lang.swift.accessibility.open'.freeze
+        'source.lang.swift.accessibility.fileprivate'
+      ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'
+      ACCESSIBILITY_PUBLIC = 'source.lang.swift.accessibility.public'
+      ACCESSIBILITY_OPEN = 'source.lang.swift.accessibility.open'
 
       def initialize(accessibility)
         @level = case accessibility

data/lib/jazzy/source_declaration/type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/inflector'
 
 module Jazzy
@@ -23,6 +25,12 @@ module Jazzy
         @type && @type[:jazzy]
       end
 
+      # kinds that are 'global' and should get their own pages
+      # with --separate-global-declarations
+      def global?
+        @type && @type[:global]
+      end
+
       # name to use for type subdirectory in URLs for back-compatibility
       def url_name
         @type && (@type[:url] || @type[:jazzy])
@@ -118,6 +126,10 @@ module Jazzy
         kind == 'source.lang.swift.decl.typealias'
       end
 
+      def swift_global_function?
+        kind == 'source.lang.swift.decl.function.free'
+      end
+
       def param?
         # SourceKit strangely categorizes initializer parameters as local
         # variables, so both kinds represent a parameter in jazzy.
@@ -141,7 +153,7 @@ module Jazzy
         Type.new('Overview')
       end
 
-      MARKDOWN_KIND = 'document.markdown'.freeze
+      MARKDOWN_KIND = 'document.markdown'
 
       def self.markdown
         Type.new(MARKDOWN_KIND)
@@ -180,19 +192,23 @@ module Jazzy
         'sourcekitten.source.lang.objc.decl.category' => {
           jazzy: 'Category',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.class' => {
           jazzy: 'Class',
           dash: 'Class',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.constant' => {
           jazzy: 'Constant',
           dash: 'Constant',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.enum' => {
           jazzy: 'Enumeration',
           url: 'Enum',
           dash: 'Enum',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.enumcase' => {
           jazzy: 'Enumeration Case',
@@ -217,10 +233,12 @@ module Jazzy
         'sourcekitten.source.lang.objc.decl.protocol' => {
           jazzy: 'Protocol',
           dash: 'Protocol',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.typedef' => {
           jazzy: 'Type Definition',
           dash: 'Type',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.mark' => {
           jazzy: 'Mark',
@@ -229,11 +247,13 @@ module Jazzy
         'sourcekitten.source.lang.objc.decl.function' => {
           jazzy: 'Function',
           dash: 'Function',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.struct' => {
           jazzy: 'Structure',
           url: 'Struct',
           dash: 'Struct',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.field' => {
           jazzy: 'Field',
@@ -300,6 +320,7 @@ module Jazzy
         'source.lang.swift.decl.class' => {
           jazzy: 'Class',
           dash: 'Class',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.constructor' => {
           jazzy: 'Initializer',
@@ -312,6 +333,7 @@ module Jazzy
         'source.lang.swift.decl.var.global' => {
           jazzy: 'Global Variable',
           dash: 'Global',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.enumcase' => {
           jazzy: 'Enumeration Case',
@@ -325,30 +347,37 @@ module Jazzy
           jazzy: 'Enumeration',
           url: 'Enum',
           dash: 'Enum',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension' => {
           jazzy: 'Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.class' => {
           jazzy: 'Class Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.enum' => {
           jazzy: 'Enumeration Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.protocol' => {
           jazzy: 'Protocol Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.struct' => {
           jazzy: 'Structure Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.free' => {
           jazzy: 'Function',
           dash: 'Function',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.method.instance' => {
           jazzy: 'Instance Method',
@@ -369,6 +398,7 @@ module Jazzy
         'source.lang.swift.decl.protocol' => {
           jazzy: 'Protocol',
           dash: 'Protocol',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.method.static' => {
           jazzy: 'Static Method',
@@ -382,6 +412,7 @@ module Jazzy
           jazzy: 'Structure',
           url: 'Struct',
           dash: 'Struct',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.subscript' => {
           jazzy: 'Subscript',
@@ -391,6 +422,7 @@ module Jazzy
           jazzy: 'Type Alias',
           url: 'Typealias',
           dash: 'Alias',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.generic_type_param' => {
           jazzy: 'Generic Type Parameter',

data/lib/jazzy/source_document.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'pathname'
 
 require 'jazzy/jazzy_markdown'
@@ -43,6 +45,7 @@ module Jazzy
 
     def content(source_module)
       return readme_content(source_module) if name == 'index'
+
       overview
     end
 
@@ -51,7 +54,7 @@ module Jazzy
     end
 
     def config_readme
-      readme_path.read if readme_path && readme_path.exist?
+      readme_path.read if readme_path&.exist?
     end
 
     def fallback_readme
@@ -67,7 +70,7 @@ module Jazzy
         ### License
 
         # <a href="#{license[:url]}">#{license[:license]}</a>
-        <<-EOS
+        <<-README
 # #{podspec.name}
 
 ### #{podspec.summary}
@@ -83,15 +86,15 @@ pod '#{podspec.name}'
 ### Authors
 
 #{source_module.author_name}
-EOS
+        README
       else
-        <<-EOS
+        <<-README
 # #{source_module.name}
 
 ### Authors
 
 #{source_module.author_name}
-EOS
+        README
       end
     end
   end

data/lib/jazzy/source_host.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Jazzy
+  # Deal with different source code repositories
+  module SourceHost
+    # Factory to create the right source host
+    def self.create(options)
+      return unless options.source_host_url || options.source_host_files_url
+
+      case options.source_host
+      when :github then GitHub.new
+      when :gitlab then GitLab.new
+      when :bitbucket then BitBucket.new
+      end
+    end
+
+    # Use GitHub as the default behaviour.
+    class GitHub
+      include Config::Mixin
+
+      # Human readable name, appears in UI
+      def name
+        'GitHub'
+      end
+
+      # Jazzy extension with logo
+      def extension
+        name.downcase
+      end
+
+      # Logo image filename within extension
+      def image
+        'gh.png'
+      end
+
+      # URL to link to from logo
+      def url
+        config.source_host_url
+      end
+
+      # URL to link to from a SourceDeclaration.
+      # Compare using `realpath` because `item.file` comes out of
+      # SourceKit/etc.
+      def item_url(item)
+        return unless files_url && item.file
+
+        realpath = item.file.realpath
+        return unless realpath.to_path.start_with?(local_root_realpath)
+
+        path = realpath.relative_path_from(local_root_realpath)
+        fragment =
+          if item.start_line && (item.start_line != item.end_line)
+            item_url_multiline_fragment(item.start_line, item.end_line)
+          else
+            item_url_line_fragment(item.line)
+          end
+
+        "#{files_url}/#{path}##{fragment}"
+      end
+
+      private
+
+      def files_url
+        config.source_host_files_url
+      end
+
+      def local_root_realpath
+        @local_root_realpath ||= config.source_directory.realpath.to_path
+      end
+
+      # Source host's line numbering link scheme
+      def item_url_line_fragment(line)
+        "L#{line}"
+      end
+
+      def item_url_multiline_fragment(start_line, end_line)
+        "L#{start_line}-L#{end_line}"
+      end
+    end
+
+    # GitLab very similar to GitHub
+    class GitLab < GitHub
+      def name
+        'GitLab'
+      end
+
+      def image
+        'gitlab.svg'
+      end
+    end
+
+    # BitBucket has its own line number system
+    class BitBucket < GitHub
+      def name
+        'Bitbucket'
+      end
+
+      def image
+        'bitbucket.svg'
+      end
+
+      def item_url_line_fragment(line)
+        "lines-#{line}"
+      end
+
+      def item_url_multiline_fragment(start_line, end_line)
+        "lines-#{start_line}:#{end_line}"
+      end
+    end
+  end
+end

data/lib/jazzy/source_mark.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
   class SourceMark
     attr_accessor :name
@@ -8,24 +10,24 @@ module Jazzy
       return unless mark_string
 
       # Format: 'MARK: - NAME -' with dashes optional
-      mark_string.sub!(/^MARK: /, '')
+      mark_content = mark_string.sub(/^MARK: /, '')
 
-      if mark_string.empty?
+      if mark_content.empty?
         # Empty
         return
-      elsif mark_string == '-'
+      elsif mark_content == '-'
         # Separator
         self.has_start_dash = true
         return
       end
 
-      self.has_start_dash = mark_string.start_with?('- ')
-      self.has_end_dash = mark_string.end_with?(' -')
+      self.has_start_dash = mark_content.start_with?('- ')
+      self.has_end_dash = mark_content.end_with?(' -')
 
       start_index = has_start_dash ? 2 : 0
       end_index = has_end_dash ? -3 : -1
 
-      self.name = mark_string[start_index..end_index]
+      self.name = mark_content[start_index..end_index]
     end
 
     def self.new_generic_requirements(requirements)