jazzy 0.9.3 → 0.11.0

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/documentation_generator.rb

@@ -11,15 +11,8 @@ module Jazzy
       documentation_entries.map do |file_path|
         SourceDocument.new.tap do |sd|
           sd.name = File.basename(file_path, '.md')
-          sd.url = sd.name.downcase.strip
-                     .tr(' ', '-').gsub(/[^\w-]/, '') + '.html'
-          sd.type = SourceDeclaration::Type.new 'document.markdown'
-          sd.children = []
           sd.overview = overview Pathname(file_path)
           sd.usr = 'documentation.' + sd.name
-          sd.abstract = ''
-          sd.return = ''
-          sd.parameters = []
         end
       end
     end

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.9.3'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.11.0'.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 = (config.swift_version || '4')[0] + '.0'
-            args << "SWIFT_VERSION=\"#{swift_version}\""
             SourceKitten.run_sourcekitten(args)
           end
         end
@@ -97,6 +96,34 @@ module Jazzy
 
     private_class_method :github_file_prefix
 
+    # Latest valid value for SWIFT_VERSION.
+    LATEST_SWIFT_VERSION = '5'.freeze
+
+    # All valid values for SWIFT_VERSION that are longer
+    # than a major version number.  Ordered ascending.
+    LONG_SWIFT_VERSIONS = ['4.2'].freeze
+
+    # Go from a full Swift version like 4.2.1 to
+    # something valid for SWIFT_VERSION.
+    def compiler_swift_version(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
@@ -107,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
@@ -116,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

@@ -8,12 +8,15 @@ module Jazzy
     # static type of declared element (e.g. String.Type -> ())
     attr_accessor :typename
 
-    def type?(type_kind)
-      respond_to?(:type) && type.kind == type_kind
+    # Give the item its own page or just inline into parent?
+    def render_as_page?
+      children.any?
     end
 
-    def render?
-      type?('document.markdown') || children.count != 0
+    # When referencing this item from its parent category,
+    # include the content or just link to it directly?
+    def omit_content_from_parent?
+      false
     end
 
     # Element containing this declaration in the code
@@ -99,6 +102,18 @@ module Jazzy
     attr_accessor :end_line
     attr_accessor :nav_order
     attr_accessor :url_name
+    attr_accessor :deprecated
+    attr_accessor :deprecation_message
+    attr_accessor :unavailable
+    attr_accessor :unavailable_message
+
+    def usage_discouraged?
+      unavailable || deprecated
+    end
+
+    def filepath
+      CGI.unescape(url)
+    end
 
     def alternative_abstract
       if file = alternative_abstract_file

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_declaration/type.rb

@@ -129,6 +129,16 @@ module Jazzy
         Type.new('Overview')
       end
 
+      MARKDOWN_KIND = 'document.markdown'.freeze
+
+      def self.markdown
+        Type.new(MARKDOWN_KIND)
+      end
+
+      def markdown?
+        kind == MARKDOWN_KIND
+      end
+
       def hash
         kind.hash
       end
@@ -140,7 +150,7 @@ module Jazzy
 
       TYPES = {
         # Markdown
-        'document.markdown' => {
+        MARKDOWN_KIND => {
           jazzy: 'Guide',
           dash: 'Guide',
         }.freeze,

data/lib/jazzy/source_document.rb

@@ -3,25 +3,42 @@ require 'pathname'
 require 'jazzy/jazzy_markdown'
 
 module Jazzy
+  # Standalone markdown docs including index.html
   class SourceDocument < SourceDeclaration
     attr_accessor :overview
     attr_accessor :readme_path
 
+    def initialize
+      super
+      self.children = []
+      self.parameters = []
+      self.abstract = ''
+      self.type = SourceDeclaration::Type.markdown
+      self.mark = SourceMark.new
+    end
+
     def self.make_index(readme_path)
       SourceDocument.new.tap do |sd|
         sd.name = 'index'
-        sd.children = []
-        sd.type = SourceDeclaration::Type.new 'document.markdown'
+        sd.url = sd.name + '.html'
         sd.readme_path = readme_path
       end
     end
 
+    def render_as_page?
+      true
+    end
+
+    def omit_content_from_parent?
+      true
+    end
+
     def config
       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,31 @@ 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'].empty?)
+    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)
+        if options.module_name_configured
+          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,
@@ -322,6 +330,8 @@ module Jazzy
           Highlighter.highlight(make_swift_declaration(doc, declaration))
       end
 
+      make_deprecation_info(doc, declaration)
+
       unless doc['key.doc.full_as_xml']
         return process_undocumented_token(doc, declaration)
       end
@@ -335,10 +345,23 @@ module Jazzy
       @stats.add_documented
     end
 
+    def self.make_deprecation_info(doc, declaration)
+      if declaration.deprecated
+        declaration.deprecation_message =
+          Markdown.render(doc['key.deprecation_message'] || '')
+      end
+      if declaration.unavailable
+        declaration.unavailable_message =
+          Markdown.render(doc['key.unavailable_message'] || '')
+      end
+    end
+
     # Strip tags and convert entities
     def self.xml_to_text(xml)
       document = REXML::Document.new(xml)
       REXML::XPath.match(document.root, '//text()').map(&:value).join
+    rescue
+      ''
     end
 
     # Regexp to match an @attribute.  Complex to handle @available().
@@ -372,10 +395,12 @@ module Jazzy
     end
 
     def self.prefer_parsed_decl?(parsed, annotated)
-      parsed &&
-        (annotated.include?(' = default') || # SR-2608
-         parsed.match('@autoclosure|@escaping') || # SR-6321
-         parsed.include?("\n"))
+      annotated.empty? ||
+        parsed &&
+          (annotated.include?(' = default') || # SR-2608
+           parsed.match('@autoclosure|@escaping') || # SR-6321
+           parsed.include?("\n") ||
+           parsed.include?('extension '))
     end
 
     # Replace the fully qualified name of a type with its base name
@@ -404,7 +429,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
@@ -479,6 +506,8 @@ module Jazzy
         declaration.column = doc['key.doc.column']
         declaration.start_line = doc['key.parsed_scope.start']
         declaration.end_line = doc['key.parsed_scope.end']
+        declaration.deprecated = doc['key.always_deprecated']
+        declaration.unavailable = doc['key.always_unavailable']
 
         next unless make_doc_info(doc, declaration)
         make_substructure(doc, declaration)
@@ -739,28 +768,34 @@ module Jazzy
       end
     end
 
+    AUTOLINK_TEXT_FIELDS = %w[return
+                              abstract
+                              unavailable_message
+                              deprecation_message].freeze
+
+    AUTOLINK_HIGHLIGHT_FIELDS = %w[declaration
+                                   other_language_declaration].freeze
+
     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)
+        AUTOLINK_TEXT_FIELDS.each do |field|
+          if text = doc.send(field)
+            doc.send(field + '=', autolink_text(text, doc, root_decls))
+          end
         end
 
-        if doc.declaration
-          doc.declaration = autolink_text(
-            doc.declaration, doc, root_decls, true
-          )
+        AUTOLINK_HIGHLIGHT_FIELDS.each do |field|
+          if text = doc.send(field)
+            doc.send(field + '=', autolink_text(text, doc, root_decls, true))
+          end
         end
 
-        if doc.other_language_declaration
-          doc.other_language_declaration = autolink_text(
-            doc.other_language_declaration, doc, root_decls, true
-          )
+        (doc.parameters || []).each do |param|
+          param[:discussion] =
+            autolink_text(param[:discussion], doc, root_decls)
         end
       end
     end