jazzy 0.10.0 → 0.13.0

data/jazzy.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'open4'
   spec.add_runtime_dependency 'redcarpet', '~> 3.4'
   spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
-  spec.add_runtime_dependency 'sass', '~> 3.6'
+  spec.add_runtime_dependency 'sassc', '~> 2.1'
   spec.add_runtime_dependency 'sqlite3', '~> 1.3'
   spec.add_runtime_dependency 'xcinvoke', '~> 0.3.0'
 

data/lib/jazzy/config.rb

@@ -79,6 +79,14 @@ module Jazzy
       @all_config_attrs << Attribute.new(name, **opts)
     end
 
+    def self.alias_config_attr(name, forward, **opts)
+      alias_method name.to_s, forward.to_s
+      alias_method "#{name}=", "#{forward}="
+      alias_method "#{name}_configured", "#{forward}_configured"
+      alias_method "#{name}_configured=", "#{forward}_configured="
+      @all_config_attrs << Attribute.new(name, **opts)
+    end
+
     class << self
       attr_reader :all_config_attrs
     end
@@ -94,6 +102,14 @@ module Jazzy
       Pathname(Dir[abs_path][0] || abs_path) # Use existing filesystem spelling
     end
 
+    def hide_swift?
+      hide_declarations == 'swift'
+    end
+
+    def hide_objc?
+      hide_declarations == 'objc'
+    end
+
     # ──────── Build ────────
 
     # rubocop:disable Layout/AlignParameters
@@ -135,9 +151,9 @@ module Jazzy
       command_line: '--hide-declarations [objc|swift] ',
       description: 'Hide declarations in the specified language. Given that ' \
                    'generating Swift docs only generates Swift declarations, ' \
-                   'this is only really useful to display just the Swift ' \
-                   'declarations & names when generating docs for an ' \
-                   'Objective-C framework.',
+                   'this is useful for hiding a specific interface for ' \
+                   'either Objective-C or mixed Objective-C and Swift ' \
+                   'projects.',
       default: ''
 
     config_attr :config_file,
@@ -146,15 +162,21 @@ module Jazzy
                     'Default: .jazzy.yaml in source directory or ancestor'],
       parse: ->(cf) { expand_path(cf) }
 
-    config_attr :xcodebuild_arguments,
-      command_line: ['-x', '--xcodebuild-arguments arg1,arg2,…argN', Array],
-      description: 'Arguments to forward to xcodebuild',
+    config_attr :build_tool_arguments,
+      command_line: ['-b', '--build-tool-arguments arg1,arg2,…argN', Array],
+      description: 'Arguments to forward to xcodebuild, swift build, or ' \
+                   'sourcekitten.',
       default: []
 
+    alias_config_attr :xcodebuild_arguments, :build_tool_arguments,
+      command_line: ['-x', '--xcodebuild-arguments arg1,arg2,…argN', Array],
+      description: 'Back-compatibility alias for build_tool_arguments.'
+
     config_attr :sourcekitten_sourcefile,
-      command_line: ['-s', '--sourcekitten-sourcefile FILEPATH'],
-      description: 'File generated from sourcekitten output to parse',
-      parse: ->(s) { expand_path(s) }
+      command_line: ['-s', '--sourcekitten-sourcefile filepath1,…filepathN',
+                     Array],
+      description: 'File(s) generated from sourcekitten output to parse',
+      parse: ->(paths) { [paths].flatten.map { |path| expand_path(path) } }
 
     config_attr :source_directory,
       command_line: '--source-directory DIRPATH',
@@ -192,6 +214,20 @@ module Jazzy
         end
       end
 
+    SWIFT_BUILD_TOOLS = %w[spm xcodebuild].freeze
+
+    config_attr :swift_build_tool,
+      command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
+      description: 'Control whether Jazzy uses Swift Package Manager or '\
+                   'xcodebuild to build the module to be documented.  By '\
+                   'default it uses xcodebuild if there is a .xcodeproj '\
+                   'file in the source directory.',
+      parse: ->(tool) do
+        return tool.to_sym if SWIFT_BUILD_TOOLS.include?(tool)
+        raise "Unsupported swift_build_tool #{tool}, "\
+              "supported values: #{SWIFT_BUILD_TOOLS.join(', ')}"
+      end
+
     # ──────── Metadata ────────
 
     config_attr :author_name,

data/lib/jazzy/doc.rb

@@ -32,10 +32,6 @@ module Jazzy
       config.objc_mode && config.hide_declarations != 'objc'
     end
 
-    def language
-      objc_first? ? 'Objective-C' : 'Swift'
-    end
-
     def language_stub
       objc_first? ? 'objc' : 'swift'
     end

data/lib/jazzy/doc_builder.rb

@@ -1,7 +1,7 @@
 require 'fileutils'
 require 'mustache'
 require 'pathname'
-require 'sass'
+require 'sassc'
 
 require 'jazzy/config'
 require 'jazzy/doc'
@@ -53,23 +53,16 @@ module Jazzy
     # @param [Config] options
     # @return [SourceModule] the documented source module
     def self.build(options)
-      if options.sourcekitten_sourcefile
-        stdout = options.sourcekitten_sourcefile.read
+      if options.sourcekitten_sourcefile_configured
+        stdout = '[' + options.sourcekitten_sourcefile.map(&:read)
+                              .join(',') + ']'
+      elsif options.podspec_configured
+        pod_documenter = PodspecDocumenter.new(options.podspec)
+        stdout = pod_documenter.sourcekitten_output(options)
       else
-        if options.podspec_configured
-          pod_documenter = PodspecDocumenter.new(options.podspec)
-          stdout = pod_documenter.sourcekitten_output(options)
-        else
-          stdout = Dir.chdir(options.source_directory) do
-            arguments = SourceKitten.arguments_from_options(options)
-            SourceKitten.run_sourcekitten(arguments)
-          end
-        end
-        unless $?.success?
-          warn 'Please pass in xcodebuild arguments using -x'
-          warn 'If build arguments are correct, please file an issue on ' \
-            'https://github.com/realm/jazzy/issues'
-          exit $?.exitstatus || 1
+        stdout = Dir.chdir(options.source_directory) do
+          arguments = SourceKitten.arguments_from_options(options)
+          SourceKitten.run_sourcekitten(arguments)
         end
       end
 
@@ -95,10 +88,9 @@ module Jazzy
     def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
         next unless doc.render_as_page?
-        # Assuming URL is relative to documentation root:
-        path = output_dir + (doc.url || "#{doc.name}.html")
+        # Filepath is relative to documentation root:
+        path = output_dir + doc.filepath
         block.call(doc, path)
-        next if doc.name == 'index'
         each_doc(
           output_dir,
           doc.children,
@@ -198,8 +190,7 @@ module Jazzy
       assets_directory = Config.instance.theme_directory + 'assets'
       FileUtils.cp_r(assets_directory.children, destination)
       Pathname.glob(destination + 'css/**/*.scss').each do |scss|
-        contents = scss.read
-        css = Sass::Engine.new(contents, syntax: :scss).render
+        css = SassC::Engine.new(scss.read).render
         css_filename = scss.sub(/\.scss$/, '')
         css_filename.open('w') { |f| f.write(css) }
         FileUtils.rm scss
@@ -339,6 +330,7 @@ module Jazzy
         name:                       item.name,
         abstract:                   abstract,
         declaration:                item.display_declaration,
+        language:                   item.display_language,
         other_language_declaration: item.display_other_language_declaration,
         usr:                        item.usr,
         dash_type:                  item.type.dash_type,
@@ -358,9 +350,10 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
 
-    def self.make_task(mark, uid, items)
+    def self.make_task(mark, uid, items, doc_model)
       {
         name: mark.name,
+        name_html: (render(doc_model, mark.name) if mark.name),
         uid: URI.encode(uid),
         items: items,
         pre_separator: mark.has_start_dash,
@@ -384,7 +377,7 @@ module Jazzy
         else
           mark_names_counts[uid] = 1
         end
-        make_task(mark, uid, items)
+        make_task(mark, uid, items, mark_children.first)
       end
     end
 

data/lib/jazzy/docset_builder.rb

@@ -78,7 +78,7 @@ module Jazzy
             'searchIndex (name, type, path);')
           source_module.all_declarations.select(&:type).each do |doc|
             db.execute('INSERT OR IGNORE INTO searchIndex(name, type, path) ' \
-              'VALUES (?, ?, ?);', [doc.name, doc.type.dash_type, doc.url])
+              'VALUES (?, ?, ?);', [doc.name, doc.type.dash_type, doc.filepath])
           end
         end
       end

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.10.0'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.13.0'.freeze unless defined? Jazzy::VERSION
 end

data/lib/jazzy/highlighter.rb

@@ -3,6 +3,9 @@ require 'rouge'
 module Jazzy
   # This module helps highlight code
   module Highlighter
+    SWIFT = 'swift'.freeze
+    OBJC = 'objective_c'.freeze
+
     class Formatter < Rouge::Formatters::HTML
       def initialize(language)
         @language = language
@@ -16,16 +19,15 @@ module Jazzy
       end
     end
 
-    # What Rouge calls the language
-    def self.default_language
-      if Config.instance.objc_mode
-        'objective_c'
-      else
-        'swift'
-      end
+    def self.highlight_swift(source)
+      highlight(source, SWIFT)
+    end
+
+    def self.highlight_objc(source)
+      highlight(source, OBJC)
     end
 
-    def self.highlight(source, language = default_language)
+    def self.highlight(source, language)
       source && Rouge.highlight(source, language, Formatter.new(language))
     end
   end

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(/-$/, '')
@@ -82,21 +82,21 @@ module Jazzy
 
       def render_aside(type, text)
         <<-HTML
-<div class="aside aside-#{type.underscore.tr('_', '-')}">
+</ul><div class="aside aside-#{type.underscore.tr('_', '-')}">
     <p class="aside-title">#{type.underscore.humanize}</p>
     #{text}
-</div>
+</div><ul>
         HTML
       end
 
       def list(text, list_type)
         elided = text.gsub!(ELIDED_LI_TOKEN, '')
         return if text =~ /\A\s*\Z/ && elided
-        return text if text =~ /class="aside-title"/
         str = "\n"
         str << (list_type == :ordered ? "<ol>\n" : "<ul>\n")
         str << text
         str << (list_type == :ordered ? "</ol>\n" : "</ul>\n")
+        str.gsub(%r{\n?<ul>\n<\/ul>}, '')
       end
 
       def block_code(code, language)
@@ -112,7 +112,6 @@ module Jazzy
       autolink: true,
       fenced_code_blocks: true,
       no_intra_emphasis: true,
-      quote: true,
       strikethrough: true,
       space_after_headers: false,
       tables: true,

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
@@ -106,11 +130,47 @@ module Jazzy
     attr_accessor :deprecation_message
     attr_accessor :unavailable
     attr_accessor :unavailable_message
+    attr_accessor :generic_requirements
+    attr_accessor :inherited_types
 
     def usage_discouraged?
       unavailable || deprecated
     end
 
+    def filepath
+      CGI.unescape(url)
+    end
+
+    def constrained_extension?
+      type.swift_extension? &&
+        generic_requirements
+    end
+
+    def mark_for_children
+      if constrained_extension?
+        SourceMark.new_generic_requirements(generic_requirements)
+      else
+        SourceMark.new
+      end
+    end
+
+    def inherited_types?
+      inherited_types &&
+        !inherited_types.empty?
+    end
+
+    # 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
+
+    # SourceKit only sets modulename for imported modules
+    def type_from_doc_module?
+      !type.extension? ||
+        (swift? && usr && modulename.nil?)
+    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
@@ -110,6 +114,10 @@ module Jazzy
         kind == 'source.lang.swift.decl.protocol'
       end
 
+      def swift_typealias?
+        kind == 'source.lang.swift.decl.typealias'
+      end
+
       def param?
         # SourceKit strangely categorizes initializer parameters as local
         # variables, so both kinds represent a parameter in jazzy.

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)