jazzy 0.9.6 → 0.12.0

data/lib/jazzy/jazzy_markdown.rb

@@ -11,7 +11,7 @@ module Jazzy
       attr_accessor :default_language
 
       def header(text, header_level)
-        text_slug = text.gsub(/[^\w]+/, '-')
+        text_slug = text.gsub(/[^[[:word:]]]+/, '-')
                         .downcase
                         .sub(/^-/, '')
                         .sub(/-$/, '')

data/lib/jazzy/podspec_documenter.rb

@@ -18,7 +18,8 @@ module Jazzy
       Pod::Config.instance.with_changes(installation_root: installation_root,
                                         verbose: false) do
         sandbox = Pod::Sandbox.new(Pod::Config.instance.sandbox_root)
-        installer = Pod::Installer.new(sandbox, podfile)
+        swift_version = compiler_swift_version(config.swift_version)
+        installer = Pod::Installer.new(sandbox, podfile(swift_version))
         installer.install!
         stdout = Dir.chdir(sandbox.root) do
           targets = installer.pod_targets
@@ -27,8 +28,6 @@ module Jazzy
 
           targets.map do |t|
             args = %W[doc --module-name #{podspec.module_name} -- -target #{t}]
-            swift_version = compiler_swift_version(config.swift_version)
-            args << "SWIFT_VERSION=#{swift_version}"
             SourceKitten.run_sourcekitten(args)
           end
         end
@@ -107,13 +106,24 @@ module Jazzy
     # Go from a full Swift version like 4.2.1 to
     # something valid for SWIFT_VERSION.
     def compiler_swift_version(user_version)
-      return LATEST_SWIFT_VERSION unless user_version
+      unless user_version
+        return podspec_swift_version || LATEST_SWIFT_VERSION
+      end
 
       LONG_SWIFT_VERSIONS.select do |version|
         user_version.start_with?(version)
       end.last || "#{user_version[0]}.0"
     end
 
+    def podspec_swift_version
+      # `swift_versions` exists from CocoaPods 1.7
+      if podspec.respond_to?('swift_versions')
+        podspec.swift_versions.max
+      else
+        podspec.swift_version
+      end
+    end
+
     # @!group SourceKitten output helper methods
 
     def pod_path
@@ -124,7 +134,8 @@ module Jazzy
       end
     end
 
-    def podfile
+    # rubocop:disable Metrics/MethodLength
+    def podfile(swift_version)
       podspec = @podspec
       path = pod_path
       @podfile ||= Pod::Podfile.new do
@@ -133,8 +144,7 @@ module Jazzy
                  deterministic_uuids: false
 
         [podspec, *podspec.recursive_subspecs].each do |ss|
-          # test_specification exists from CocoaPods 1.3.0
-          next if ss.respond_to?('test_specification') && ss.test_specification
+          next if ss.test_specification
 
           ss.available_platforms.each do |p|
             # Travis builds take too long when building docs for all available
@@ -147,10 +157,12 @@ module Jazzy
               use_frameworks!
               platform p.name, p.deployment_target
               pod ss.name, path: path.realpath.to_s
+              current_target_definition.swift_version = swift_version
             end
           end
         end
       end
     end
+    # rubocop:enable Metrics/MethodLength
   end
 end

data/lib/jazzy/source_declaration.rb

@@ -1,6 +1,7 @@
 require 'jazzy/source_declaration/access_control_level'
 require 'jazzy/source_declaration/type'
 
+# rubocop:disable Metrics/ClassLength
 module Jazzy
   class SourceDeclaration
     # kind of declaration (e.g. class, variable, function)
@@ -13,6 +14,14 @@ module Jazzy
       children.any?
     end
 
+    def swift?
+      type.swift_type?
+    end
+
+    def highlight_language
+      swift? ? Highlighter::SWIFT : Highlighter::OBJC
+    end
+
     # When referencing this item from its parent category,
     # include the content or just link to it directly?
     def omit_content_from_parent?
@@ -67,17 +76,32 @@ module Jazzy
       name.split(/[\(\)]/) if type.objc_category?
     end
 
+    def swift_objc_extension?
+      type.swift_extension? && usr && usr.start_with?('c:objc')
+    end
+
+    def swift_extension_objc_name
+      return unless type.swift_extension? && usr
+
+      usr.split('(cs)').last
+    end
+
+    # The language in the templates for display
+    def display_language
+      return 'Swift' if swift?
+
+      Config.instance.hide_objc? ? 'Swift' : 'Objective-C'
+    end
+
     def display_declaration
-      if Config.instance.hide_declarations == 'objc'
-        other_language_declaration
-      else
-        declaration
-      end
+      return declaration if swift?
+
+      Config.instance.hide_objc? ? other_language_declaration : declaration
     end
 
     def display_other_language_declaration
       other_language_declaration unless
-        %w[swift objc].include? Config.instance.hide_declarations
+        Config.instance.hide_objc? || Config.instance.hide_swift?
     end
 
     attr_accessor :file
@@ -111,6 +135,10 @@ module Jazzy
       unavailable || deprecated
     end
 
+    def filepath
+      CGI.unescape(url)
+    end
+
     def alternative_abstract
       if file = alternative_abstract_file
         Pathname(file).read

data/lib/jazzy/source_declaration/type.rb

@@ -77,6 +77,10 @@ module Jazzy
         kind == 'sourcekitten.source.lang.objc.decl.class'
       end
 
+      def swift_type?
+        kind.include? 'swift'
+      end
+
       def swift_enum_case?
         kind == 'source.lang.swift.decl.enumcase'
       end

data/lib/jazzy/source_document.rb

@@ -20,6 +20,7 @@ module Jazzy
     def self.make_index(readme_path)
       SourceDocument.new.tap do |sd|
         sd.name = 'index'
+        sd.url = sd.name + '.html'
         sd.readme_path = readme_path
       end
     end
@@ -36,8 +37,8 @@ module Jazzy
       Config.instance
     end
 
-    def url
-      name.downcase.strip.tr(' ', '-').gsub(/[^\w-]/, '') + '.html'
+    def url_name
+      name.downcase.strip.tr(' ', '-').gsub(/[^[[:word:]]-]/, '')
     end
 
     def content(source_module)

data/lib/jazzy/sourcekitten.rb

@@ -65,7 +65,7 @@ module Jazzy
       type_categories, uncategorized = group_type_categories(
         docs, custom_categories.any? ? 'Other ' : ''
       )
-      custom_categories + type_categories + uncategorized
+      custom_categories + merge_categories(type_categories) + uncategorized
     end
 
     def self.group_custom_categories(docs)
@@ -98,6 +98,19 @@ module Jazzy
       [group.compact, docs]
     end
 
+    # Join categories with the same name (eg. ObjC and Swift classes)
+    def self.merge_categories(categories)
+      merged = []
+      categories.each do |new_category|
+        if existing = merged.find { |c| c.name == new_category.name }
+          existing.children += new_category.children
+        else
+          merged.append(new_category)
+        end
+      end
+      merged
+    end
+
     def self.make_group(group, name, abstract, url_name = nil)
       group.reject! { |doc| doc.name.empty? }
       unless group.empty?
@@ -126,12 +139,11 @@ module Jazzy
     # @return [Hash] input docs with URLs
     def self.make_doc_urls(docs)
       docs.each do |doc|
-        if !doc.parent_in_docs || doc.children.count > 0
-          # Create HTML page for this doc if it has children or is root-level
+        if doc.render_as_page?
           doc.url = (
             subdir_for_doc(doc) +
             [sanitize_filename(doc) + '.html']
-          ).join('/')
+          ).map { |path| ERB::Util.url_encode(path) }.join('/')
           doc.children = make_doc_urls(doc.children)
         else
           # Don't create HTML page for this doc if it doesn't have children
@@ -140,8 +152,8 @@ module Jazzy
             warn 'A compile error prevented ' + doc.fully_qualified_name +
                  ' from receiving a unique USR. Documentation may be ' \
                  'incomplete. Please check for compile errors by running ' \
-                 '`xcodebuild ' \
-                 "#{Config.instance.xcodebuild_arguments.shelljoin}`."
+                 '`xcodebuild` or `swift build` with arguments ' \
+                 "`#{Config.instance.build_tool_arguments.shelljoin}`."
           end
           id = doc.usr
           unless id
@@ -159,17 +171,17 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
 
-    # Determine the subdirectory in which a doc should be placed
+    # Determine the subdirectory in which a doc should be placed.
+    # Guides in the root for back-compatibility.
+    # Declarations under outer namespace type (Structures, Classes, etc.)
     def self.subdir_for_doc(doc)
-      # We always want to create top-level subdirs according to type (Struct,
-      # Class, etc).
+      return [] if doc.type.markdown?
       top_level_decl = doc.namespace_path.first
-      if top_level_decl && top_level_decl.type && top_level_decl.type.name
-        # File program elements under top ancestor’s type (Struct, Class, etc.)
+      if top_level_decl.type.name
         [top_level_decl.type.plural_url_name] +
           doc.namespace_ancestors.map(&:name)
       else
-        # Categories live in their own directory
+        # Category - in the root
         []
       end
     end
@@ -183,22 +195,33 @@ module Jazzy
       end.select { |x| x }.flatten(1)
     end
 
+    def self.use_spm?(options)
+      options.swift_build_tool == :spm ||
+        (!options.swift_build_tool_configured &&
+         Dir['*.xcodeproj', '*.xcworkspace'].empty? &&
+         !options.build_tool_arguments.include?('-project') &&
+         !options.build_tool_arguments.include?('-workspace'))
+    end
+
     # Builds SourceKitten arguments based on Jazzy options
     def self.arguments_from_options(options)
       arguments = ['doc']
-      arguments += if options.objc_mode
-                     objc_arguments_from_options(options)
-                   elsif !options.module_name.empty?
-                     ['--module-name', options.module_name, '--']
-                   else
-                     ['--']
-                   end
-      arguments + options.xcodebuild_arguments
+      if options.objc_mode
+        arguments += objc_arguments_from_options(options)
+      else
+        arguments += ['--spm'] if use_spm?(options)
+        unless options.module_name.empty?
+          arguments += ['--module-name', options.module_name]
+        end
+        arguments += ['--']
+      end
+
+      arguments + options.build_tool_arguments
     end
 
     def self.objc_arguments_from_options(options)
       arguments = []
-      if options.xcodebuild_arguments.empty?
+      if options.build_tool_arguments.empty?
         arguments += ['--objc', options.umbrella_header.to_s, '--', '-x',
                       'objective-c', '-isysroot',
                       `xcrun --show-sdk-path --sdk #{options.sdk}`.chomp,
@@ -252,8 +275,13 @@ module Jazzy
     def self.should_document?(doc)
       return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
 
+      type = SourceDeclaration::Type.new(doc['key.kind'])
+
       # Always document Objective-C declarations.
-      return true if Config.instance.objc_mode
+      return true unless type.swift_type?
+
+      # Don't document Swift types if we are hiding Swift
+      return false if Config.instance.hide_swift?
 
       # Don't document @available declarations with no USR, since it means
       # they're unavailable.
@@ -262,7 +290,6 @@ module Jazzy
       end
 
       # Document extensions & enum elements, since we can't tell their ACL.
-      type = SourceDeclaration::Type.new(doc['key.kind'])
       return true if type.swift_enum_element?
       if type.swift_extension?
         return Array(doc['key.substructure']).any? do |subdoc|
@@ -286,14 +313,14 @@ module Jazzy
       make_default_doc_info(declaration)
 
       filepath = doc['key.filepath']
-      objc = Config.instance.objc_mode
-      if objc || should_mark_undocumented(filepath)
+
+      if !declaration.swift? || should_mark_undocumented(filepath)
         @stats.add_undocumented(declaration)
         return nil if @skip_undocumented
         declaration.abstract = undocumented_abstract
       else
         declaration.abstract = Markdown.render(doc['key.doc.comment'] || '',
-                                               Highlighter.default_language)
+                                               declaration.highlight_language)
       end
 
       declaration
@@ -312,16 +339,7 @@ module Jazzy
     def self.make_doc_info(doc, declaration)
       return unless should_document?(doc)
 
-      if Config.instance.objc_mode
-        declaration.declaration =
-          Highlighter.highlight(doc['key.parsed_declaration'])
-        declaration.other_language_declaration =
-          Highlighter.highlight(doc['key.swift_declaration'], 'swift')
-      else
-        declaration.declaration =
-          Highlighter.highlight(make_swift_declaration(doc, declaration))
-      end
-
+      highlight_declaration(doc, declaration)
       make_deprecation_info(doc, declaration)
 
       unless doc['key.doc.full_as_xml']
@@ -329,7 +347,7 @@ module Jazzy
       end
 
       declaration.abstract = Markdown.render(doc['key.doc.comment'] || '',
-                                             Highlighter.default_language)
+                                             declaration.highlight_language)
       declaration.discussion = ''
       declaration.return = Markdown.rendered_returns
       declaration.parameters = parameters(doc, Markdown.rendered_parameters)
@@ -337,6 +355,18 @@ module Jazzy
       @stats.add_documented
     end
 
+    def self.highlight_declaration(doc, declaration)
+      if declaration.swift?
+        declaration.declaration =
+          Highlighter.highlight_swift(make_swift_declaration(doc, declaration))
+      else
+        declaration.declaration =
+          Highlighter.highlight_objc(doc['key.parsed_declaration'])
+        declaration.other_language_declaration =
+          Highlighter.highlight_swift(doc['key.swift_declaration'])
+      end
+    end
+
     def self.make_deprecation_info(doc, declaration)
       if declaration.deprecated
         declaration.deprecation_message =
@@ -413,6 +443,9 @@ module Jazzy
       # From source code
       parsed_decl = doc['key.parsed_declaration']
 
+      # Don't present type attributes on extensions
+      return parsed_decl if declaration.type.extension?
+
       decl =
         if prefer_parsed_decl?(parsed_decl, annotated_decl_body)
           # Strip any attrs captured by parsed version
@@ -462,8 +495,7 @@ module Jazzy
         declaration.type = SourceDeclaration::Type.new(doc['key.kind'])
         declaration.typename = doc['key.typename']
         declaration.objc_name = doc['key.name']
-        documented_name = if Config.instance.hide_declarations == 'objc' &&
-                             doc['key.swift_name']
+        documented_name = if Config.instance.hide_objc? && doc['key.swift_name']
                             doc['key.swift_name']
                           else
                             declaration.objc_name
@@ -517,6 +549,10 @@ module Jazzy
       decls.map do |decl|
         next decl unless decl.type.extension? && decl.name.include?('.')
 
+        # Don't expand the Swift namespace if we're in ObjC mode.
+        # ex: NS_SWIFT_NAME(Foo.Bar) should not create top-level Foo
+        next decl if decl.swift_objc_extension? && !Config.instance.hide_objc?
+
         name_parts = decl.name.split('.')
         decl.name = name_parts.pop
         expand_extension(decl, name_parts, decls)
@@ -567,11 +603,18 @@ module Jazzy
 
     # Two declarations get merged if they have the same deduplication key.
     def self.deduplication_key(decl, root_decls)
-      if decl.type.swift_extensible? || decl.type.swift_extension?
+      # Swift extension of objc class
+      if decl.swift_objc_extension?
+        [decl.swift_extension_objc_name, :objc_class_and_categories]
+      # Swift type or Swift extension of Swift type
+      elsif decl.type.swift_extensible? || decl.type.swift_extension?
         [decl.usr, decl.name]
+      # Objc categories and classes
       elsif mergeable_objc?(decl, root_decls)
-        name, _ = decl.objc_category_name || decl.name
+        # Using the ObjC name to match swift_objc_extension.
+        name, _ = decl.objc_category_name || decl.objc_name
         [name, :objc_class_and_categories]
+      # Non-mergable declarations (funcs, typedefs etc...)
       else
         [decl.usr, decl.name, decl.type.kind]
       end
@@ -817,17 +860,14 @@ module Jazzy
       @min_acl = min_acl
       @skip_undocumented = skip_undocumented
       @stats = Stats.new
-      sourcekitten_json = filter_files(JSON.parse(sourcekitten_output))
+      sourcekitten_json = filter_files(JSON.parse(sourcekitten_output).flatten)
       docs = make_source_declarations(sourcekitten_json).concat inject_docs
       docs = expand_extensions(docs)
       docs = deduplicate_declarations(docs)
-      if Config.instance.objc_mode
-        docs = reject_objc_types(docs)
-      else
-        # Remove top-level enum cases because it means they have an ACL lower
-        # than min_acl
-        docs = docs.reject { |doc| doc.type.swift_enum_element? }
-      end
+      docs = reject_objc_types(docs)
+      # Remove top-level enum cases because it means they have an ACL lower
+      # than min_acl
+      docs = docs.reject { |doc| doc.type.swift_enum_element? }
       ungrouped_docs = docs
       docs = group_docs(docs)
       make_doc_urls(docs)