jazzy 0.9.5 → 0.11.2

data/Rakefile

@@ -75,13 +75,14 @@ begin
 
     # Remove files not used for the comparison
     # To keep the git diff clean
-    files_glob = 'spec/integration_specs/*/after/{*,.*}'
+    specs_root = 'spec/integration_specs/*/after'
+    files_glob = "#{specs_root}/{*,.*}"
     files_to_delete = FileList[files_glob]
       .exclude('**/.', '**/..')
-      .exclude('spec/integration_specs/*/after/*docs',
-               'spec/integration_specs/*/after/execution_output.txt')
-      .include('**/*.dsidx')
-      .include('**/*.tgz')
+      .exclude("#{specs_root}/*docs",
+               "#{specs_root}/execution_output.txt")
+      .include("#{specs_root}/**/*.dsidx")
+      .include("#{specs_root}/**/*.tgz")
     files_to_delete.each do |file_to_delete|
       sh "rm -rf '#{file_to_delete}'"
     end
@@ -103,7 +104,7 @@ begin
   task :sourcekitten do
     sk_dir = 'SourceKitten'
     Dir.chdir(sk_dir) do
-      `swift build -c release -Xswiftc -static-stdlib`
+      `swift build -c release`
     end
     FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
   end

data/jazzy.gemspec

@@ -17,13 +17,13 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split($/)
   spec.executables   << 'jazzy'
 
-  spec.add_runtime_dependency 'cocoapods', '~> 1.5.3'
-  spec.add_runtime_dependency 'mustache', '~> 1.1.0'
+  spec.add_runtime_dependency 'cocoapods', '~> 1.5'
+  spec.add_runtime_dependency 'mustache', '~> 1.1'
   spec.add_runtime_dependency 'open4'
-  spec.add_runtime_dependency 'redcarpet', '~> 3.4.0'
+  spec.add_runtime_dependency 'redcarpet', '~> 3.4'
   spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
-  spec.add_runtime_dependency 'sass', '~> 3.6.0'
-  spec.add_runtime_dependency 'sqlite3', '~> 1.3.13'
+  spec.add_runtime_dependency 'sassc', '~> 2.1'
+  spec.add_runtime_dependency 'sqlite3', '~> 1.3'
   spec.add_runtime_dependency 'xcinvoke', '~> 0.3.0'
 
   spec.add_development_dependency 'bundler', '~> 1.7'

data/lib/jazzy/config.rb

@@ -2,7 +2,6 @@ require 'optparse'
 require 'pathname'
 require 'uri'
 
-require 'jazzy/doc'
 require 'jazzy/podspec_documenter'
 require 'jazzy/source_declaration/access_control_level'
 
@@ -80,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
@@ -147,11 +154,16 @@ 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',
@@ -193,6 +205,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,
@@ -213,9 +239,16 @@ module Jazzy
 
     config_attr :version,
       command_line: '--module-version VERSION',
-      description: 'module version. will be used when generating docset',
+      description: 'Version string to use as part of the the default docs '\
+                   'title and inside the docset.',
       default: '1.0'
 
+    config_attr :title,
+      command_line: '--title TITLE',
+      description: 'Title to display at the top of each page, overriding the '\
+                   'default generated from module name and version.',
+      default: ''
+
     config_attr :copyright,
       command_line: '--copyright COPYRIGHT_MARKDOWN',
       description: 'copyright markdown rendered at the bottom of the docs pages'

data/lib/jazzy/doc.rb

@@ -8,10 +8,11 @@ require 'jazzy/jazzy_markdown'
 
 module Jazzy
   class Doc < Mustache
+    include Config::Mixin
+
     self.template_name = 'doc'
 
     def copyright
-      config = Config.instance
       copyright = config.copyright || (
         # Fake date is used to keep integration tests consistent
         date = ENV['JAZZY_FAKE_DATE'] || DateTime.now.strftime('%Y-%m-%d')
@@ -28,7 +29,7 @@ module Jazzy
     end
 
     def objc_first?
-      Config.instance.objc_mode && Config.instance.hide_declarations != 'objc'
+      config.objc_mode && config.hide_declarations != 'objc'
     end
 
     def language
@@ -38,5 +39,21 @@ module Jazzy
     def language_stub
       objc_first? ? 'objc' : 'swift'
     end
+
+    def module_version
+      config.version_configured ? config.version : nil
+    end
+
+    def docs_title
+      if config.title_configured
+        config.title
+      elsif config.version_configured
+        # Fake version for integration tests
+        version = ENV['JAZZY_FAKE_MODULE_VERSION'] || config.version
+        "#{config.module_name} #{version} Docs"
+      else
+        "#{config.module_name} Docs"
+      end
+    end
   end
 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'
@@ -55,21 +55,13 @@ module Jazzy
     def self.build(options)
       if options.sourcekitten_sourcefile
         stdout = options.sourcekitten_sourcefile.read
+      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 +87,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 +189,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

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.9.5'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.11.2'.freeze unless defined? Jazzy::VERSION
 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(/-$/, '')

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
@@ -98,7 +97,7 @@ module Jazzy
     private_class_method :github_file_prefix
 
     # Latest valid value for SWIFT_VERSION.
-    LATEST_SWIFT_VERSION = '4.2'.freeze
+    LATEST_SWIFT_VERSION = '5'.freeze
 
     # All valid values for SWIFT_VERSION that are longer
     # than a major version number.  Ordered ascending.
@@ -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,26 +144,25 @@ 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
             # platforms for the Moya integration spec, so we just document OSX.
-            # Also Moya's RxSwift subspec doesn't yet support Swift 4, so skip
-            # that too while we're at it.
             # TODO: remove once jazzy is fast enough.
             if ENV['JAZZY_INTEGRATION_SPECS']
-              next if (p.name != :osx) || (ss.name == 'Moya/RxSwift')
+              next if p.name != :osx
             end
             target("Jazzy-#{ss.name.gsub('/', '__')}-#{p.name}") do
               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

@@ -111,6 +111,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/access_control_level.rb

@@ -26,6 +26,8 @@ module Jazzy
       end
 
       def self.from_doc(doc)
+        return AccessControlLevel.internal if implicit_deinit?(doc)
+
         accessibility = doc['key.accessibility']
         if accessibility
           acl = new(accessibility)
@@ -33,12 +35,17 @@ module Jazzy
             return acl
           end
         end
-        acl = from_explicit_declaration(doc['key.parsed_declaration'])
+        acl = from_doc_explicit_declaration(doc)
         acl || AccessControlLevel.public # fallback on public ACL
       end
 
-      def self.from_explicit_declaration(declaration_string)
-        case declaration_string
+      def self.implicit_deinit?(doc)
+        doc['key.name'] == 'deinit' &&
+          from_doc_explicit_declaration(doc).nil?
+      end
+
+      def self.from_doc_explicit_declaration(doc)
+        case doc['key.parsed_declaration']
         when /private\ / then private
         when /fileprivate\ / then fileprivate
         when /public\ / then public

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

@@ -126,12 +126,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 +139,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 +158,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 +182,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,
@@ -391,7 +401,8 @@ module Jazzy
         parsed &&
           (annotated.include?(' = default') || # SR-2608
            parsed.match('@autoclosure|@escaping') || # SR-6321
-           parsed.include?("\n"))
+           parsed.include?("\n") ||
+           parsed.include?('extension '))
     end
 
     # Replace the fully qualified name of a type with its base name
@@ -420,7 +431,9 @@ module Jazzy
           parsed_decl_body.unindent(inline_attrs.length)
         else
           # Strip ugly references to decl type name
-          unqualify_name(annotated_decl_body, declaration)
+          unqualified = unqualify_name(annotated_decl_body, declaration)
+          # Workaround for SR-9816
+          unqualified.gsub(" {\n  get\n  }", '')
         end
 
       # @available attrs only in compiler 'interface' style