jazzy 0.3.2 → 0.4.0

data/lib/jazzy/doc.rb

@@ -10,25 +10,6 @@ module Jazzy
   class Doc < Mustache
     self.template_name = 'doc'
 
-    ############################################################################
-    # TODO: Remove shortly (kept for backwards compatibility)
-    #
-    def date
-      # Fake date is used to keep integration tests consistent
-      ENV['JAZZY_FAKE_DATE'] || DateTime.now.strftime('%Y-%m-%d')
-    end
-
-    def year
-      # Fake date is used to keep integration tests consistent
-      if ENV['JAZZY_FAKE_DATE']
-        ENV['JAZZY_FAKE_DATE'][0..3]
-      else
-        DateTime.now.strftime('%Y')
-      end
-    end
-    #
-    ############################################################################
-
     def copyright
       config = Config.instance
       copyright = config.copyright || (
@@ -45,5 +26,13 @@ module Jazzy
       # Fake version is used to keep integration tests consistent
       ENV['JAZZY_FAKE_VERSION'] || Jazzy::VERSION
     end
+
+    def language
+      Config.instance.objc_mode ? 'Objective-C' : 'Swift'
+    end
+
+    def language_stub
+      Config.instance.objc_mode ? 'objc' : 'swift'
+    end
   end
 end

data/lib/jazzy/doc_builder.rb

@@ -29,14 +29,15 @@ module Jazzy
     #                     section names & child names & URLs
     def self.doc_structure_for_docs(docs)
       docs.map do |doc|
+        children = doc.children
+                   .sort_by(&:name)
+                   .sort_by(&:nav_order)
+                   .map do |child|
+          { name: child.name, url: child.url }
+        end
         {
           section: doc.name,
-          children: doc.children
-              .sort_by(&:name)
-              .sort_by(&:nav_order)
-              .map do |child|
-                { name: child.name, url: child.url }
-              end,
+          children: children,
         }
       end
     end
@@ -48,8 +49,8 @@ module Jazzy
       if options.sourcekitten_sourcefile
         stdout = options.sourcekitten_sourcefile.read
       else
-        if podspec = options.podspec
-          stdout = PodspecDocumenter.new(podspec).sourcekitten_output
+        if options.podspec_configured
+          stdout = PodspecDocumenter.new(options.podspec).sourcekitten_output
         else
           stdout = Dir.chdir(options.source_directory) do
             arguments = SourceKitten.arguments_from_options(options)
@@ -128,11 +129,21 @@ module Jazzy
 
       DocsetBuilder.new(output_dir, source_module).build!
 
-      puts "jam out ♪♫ to your fresh new docs in `#{output_dir}`"
+      friendly_path = relative_path_if_inside(output_dir, Pathname.pwd)
+      puts "jam out ♪♫ to your fresh new docs in `#{friendly_path}`"
 
       source_module
     end
 
+    def self.relative_path_if_inside(path, base_path)
+      relative = path.relative_path_from(base_path)
+      if relative.to_path =~ %r{/^..(\/|$)/}
+        path
+      else
+        relative
+      end
+    end
+
     def self.decl_for_token(token)
       if token['key.parsed_declaration']
         token['key.parsed_declaration']
@@ -188,8 +199,6 @@ module Jazzy
       doc[:structure] = source_module.doc_structure
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
-      # TODO: Remove shortly (kept for backwards compatibility)
-      doc[:author_website] = source_module.author_url
       doc[:github_url] = source_module.github_url
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
@@ -226,22 +235,27 @@ module Jazzy
       # Combine abstract and discussion into abstract
       abstract = (item.abstract || '') + (item.discussion || '')
       item_render = {
-        name: item.name,
-        abstract: Jazzy.markdown.render(abstract),
-        declaration: item.declaration,
-        usr: item.usr,
-        dash_type: item.type.dash_type,
+        name:                    item.name,
+        abstract:                render_markdown(abstract),
+        declaration:             item.declaration,
+        usr:                     item.usr,
+        dash_type:               item.type.dash_type,
+        github_token_url:        gh_token_url(item, source_module),
+        default_impl_abstract:   render_markdown(item.default_impl_abstract),
+        from_protocol_extension: item.from_protocol_extension,
+        return:                  render_markdown(item.return),
+        parameters:              (item.parameters if item.parameters.any?),
+        url:                     (item.url if item.children.any?),
+        start_line:              item.start_line,
+        end_line:                item.end_line,
       }
-      gh_token_url = gh_token_url(item, source_module)
-      item_render[:github_token_url] = gh_token_url
-      item_render[:return] = Jazzy.markdown.render(item.return) if item.return
-      item_render[:parameters] = item.parameters if item.parameters.any?
-      item_render[:url] = item.url if item.children.any?
-      item_render[:start_line] = item.start_line
-      item_render[:end_line] = item.end_line
       item_render.reject { |_, v| v.nil? }
     end
 
+    def self.render_markdown(markdown)
+      Jazzy.markdown.render(markdown) if markdown
+    end
+
     def self.make_task(mark, uid, items)
       {
         name: mark.name,
@@ -295,12 +309,10 @@ module Jazzy
       doc[:tasks] = render_tasks(source_module, doc_model.children)
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
-      # TODO: Remove shortly (kept for backwards compatibility)
-      doc[:author_website] = source_module.author_url.to_s
       doc[:github_url] = source_module.github_url
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
-      doc.render
+      doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
     end
   end
 end

data/lib/jazzy/docset_builder.rb

@@ -15,8 +15,9 @@ module Jazzy
 
       def initialize(generated_docs_dir, source_module)
         @source_module = source_module
-        @docset_dir = generated_docs_dir +
-          (config.docset_path || "docsets/#{source_module.name}.docset")
+        docset_path = config.docset_path ||
+                      "docsets/#{source_module.name}.docset"
+        @docset_dir = generated_docs_dir + docset_path
         @generated_docs_dir = generated_docs_dir
         @output_dir = docset_dir.parent
         @documents_dir = docset_dir + 'Contents/Resources/Documents/'
@@ -59,7 +60,7 @@ module Jazzy
 
       def copy_docs
         files_to_copy = Pathname.glob(generated_docs_dir + '*') -
-          [docset_dir, output_dir]
+                        [docset_dir, output_dir]
 
         FileUtils.mkdir_p documents_dir
         FileUtils.cp_r files_to_copy, documents_dir

data/lib/jazzy/executable.rb

@@ -24,7 +24,8 @@ module Jazzy
 
         require 'open4'
 
-        stdout, stderr = IO.new, IO.new($stderr)
+        stdout = IO.new
+        stderr = IO.new($stderr)
 
         options = { stdout: stdout, stderr: stderr, status: true }
         status  = Open4.spawn(env, bin, *args, options)

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.3.2' unless defined? Jazzy::VERSION
+  VERSION = '0.4.0' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/jazzy_markdown.rb

@@ -9,9 +9,9 @@ module Jazzy
 
     def header(text, header_level)
       text_slug = text.gsub(/[^a-zA-Z0-9]+/, '_')
-        .downcase
-        .sub(/^_/, '')
-        .sub(/_$/, '')
+                  .downcase
+                  .sub(/^_/, '')
+                  .sub(/_$/, '')
 
       "<a href='##{text_slug}' class='anchor' aria-hidden=true>" \
         '<span class="header-anchor"></span>' \
@@ -57,15 +57,27 @@ module Jazzy
     ELIDED_LI_TOKEN = '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'.freeze
 
     def list_item(text, _list_type)
-      return ELIDED_LI_TOKEN if text =~ SPECIAL_LIST_TYPE_REGEX
+      if text =~ SPECIAL_LIST_TYPE_REGEX
+        type = Regexp.last_match(2)
+        return ELIDED_LI_TOKEN if type =~ /parameter|returns/
+        return render_aside(type, text.sub(/#{Regexp.escape(type)}:\s+/, ''))
+      end
       str = '<li>'
       str << text.strip
       str << "</li>\n"
     end
 
+    def render_aside(type, text)
+      %(<div class="aside aside-#{type.underscore.tr('_', '-')}">
+          <p class="aside-title">#{type.underscore.humanize}</p>
+          #{text}
+        </div>)
+    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

data/lib/jazzy/podspec_documenter.rb

@@ -23,23 +23,37 @@ module Jazzy
       stdout.reduce([]) { |a, s| a + JSON.load(s) }.to_json
     end
 
-    def self.configure(config, podspec)
-      case podspec
+    def self.create_podspec(podspec_path)
+      case podspec_path
       when Pathname, String
         require 'cocoapods'
-        podspec = Pod::Specification.from_file(podspec)
+        Pod::Specification.from_file(podspec_path)
       end
+    end
 
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    def self.apply_config_defaults(podspec, config)
       return unless podspec
 
-      config.author_name = author_name(podspec)
-      config.module_name = podspec.module_name
-      config.author_url = podspec.homepage || github_file_prefix(podspec)
-      config.version = podspec.version.to_s
-      config.github_file_prefix = github_file_prefix(podspec)
-
-      podspec
+      unless config.author_name_configured
+        config.author_name = author_name(podspec)
+      end
+      unless config.module_name_configured
+        config.module_name = podspec.module_name
+      end
+      unless config.author_url_configured
+        config.author_url = podspec.homepage || github_file_prefix(podspec)
+      end
+      unless config.version_configured
+        config.version = podspec.version.to_s
+      end
+      unless config.github_file_prefix_configured
+        config.github_file_prefix = github_file_prefix(podspec)
+      end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
 
     private
 
@@ -95,7 +109,7 @@ module Jazzy
         platform :ios, '8.0'
         [podspec, *podspec.recursive_subspecs].each do |ss|
           ss.available_platforms.each do |p|
-            t = "Jazzy-#{ss.name.gsub(/\//, '__')}-#{p.name}"
+            t = "Jazzy-#{ss.name.gsub('/', '__')}-#{p.name}"
             targets << "Pods-#{t}-#{ss.root.name}"
             target(t) do
               use_frameworks!

data/lib/jazzy/readme_generator.rb

@@ -31,29 +31,29 @@ module Jazzy
 
         # <a href="#{license[:url]}">#{license[:license]}</a>
         <<-EOS
-# #{ podspec.name }
+# #{podspec.name}
 
-### #{podspec.summary }
+### #{podspec.summary}
 
-#{ podspec.description }
+#{podspec.description}
 
 ### Installation
 
 ```ruby
-pod '#{ podspec.name }'
+pod '#{podspec.name}'
 ```
 
 ### Authors
 
-#{ source_module.author_name }
+#{source_module.author_name}
 EOS
       else
         <<-EOS
-# #{ source_module.name }
+# #{source_module.name}
 
 ### Authors
 
-#{ source_module.author_name }
+#{source_module.author_name}
 EOS
       end
     end

data/lib/jazzy/source_declaration.rb

@@ -14,6 +14,8 @@ module Jazzy
     attr_accessor :name
     attr_accessor :declaration
     attr_accessor :abstract
+    attr_accessor :default_impl_abstract
+    attr_accessor :from_protocol_extension
     attr_accessor :discussion
     attr_accessor :return
     attr_accessor :children

data/lib/jazzy/source_declaration/access_control_level.rb

@@ -10,15 +10,14 @@ module Jazzy
       ACCESSIBILITY_PUBLIC   = 'source.lang.swift.accessibility.public'
 
       def initialize(accessibility)
-        if accessibility == ACCESSIBILITY_PRIVATE
-          @level = :private
-        elsif accessibility == ACCESSIBILITY_INTERNAL
-          @level = :internal
-        elsif accessibility == ACCESSIBILITY_PUBLIC
-          @level = :public
-        else
-          raise "cannot initialize AccessControlLevel with '#{accessibility}'"
-        end
+        @level = case accessibility
+                 when ACCESSIBILITY_PRIVATE then :private
+                 when ACCESSIBILITY_INTERNAL then :internal
+                 when ACCESSIBILITY_PUBLIC then :public
+                 else
+                   raise 'cannot initialize AccessControlLevel with ' \
+                     "'#{accessibility}'"
+                 end
       end
 
       def self.from_doc(doc)
@@ -34,12 +33,19 @@ module Jazzy
       end
 
       def self.from_explicit_declaration(declaration_string)
-        if declaration_string =~ /private\ /
-          return AccessControlLevel.private
-        elsif declaration_string =~ /public\ /
-          return AccessControlLevel.public
-        elsif declaration_string =~ /internal\ /
-          return AccessControlLevel.internal
+        case declaration_string
+        when /private\ / then private
+        when /public\ / then public
+        when /internal\ / then internal
+        end
+      end
+
+      def self.from_human_string(string)
+        case string.to_s.downcase
+        when 'private' then private
+        when 'internal' then internal
+        when 'public' then public
+        else raise "cannot initialize AccessControlLevel with '#{string}'"
         end
       end
 

data/lib/jazzy/source_declaration/type.rb

@@ -28,14 +28,23 @@ module Jazzy
       end
 
       def mark?
-        kind == 'source.lang.swift.syntaxtype.comment.mark'
+        kind == 'source.lang.swift.syntaxtype.comment.mark' ||
+          kind == 'sourcekitten.source.lang.objc.mark'
       end
 
-      def enum_case?
+      def objc_enum?
+        kind == 'sourcekitten.source.lang.objc.decl.enum'
+      end
+
+      def objc_typedef?
+        kind == 'sourcekitten.source.lang.objc.decl.typedef'
+      end
+
+      def swift_enum_case?
         kind == 'source.lang.swift.decl.enumcase'
       end
 
-      def enum_element?
+      def swift_enum_element?
         kind == 'source.lang.swift.decl.enumelement'
       end
 
@@ -44,13 +53,22 @@ module Jazzy
       end
 
       def declaration?
-        kind =~ /^source\.lang\.swift\.decl\..*/
+        kind.start_with?('source.lang.swift.decl') ||
+          kind.start_with?('sourcekitten.source.lang.objc.decl')
       end
 
-      def extension?
+      def swift_extension?
         kind =~ /^source\.lang\.swift\.decl\.extension.*/
       end
 
+      def swift_extensible?
+        kind =~ /^source\.lang\.swift\.decl\.(class|struct|protocol|enum)$/
+      end
+
+      def swift_protocol?
+        kind == 'source.lang.swift.decl.protocol'
+      end
+
       def param?
         # SourceKit strangely categorizes initializer parameters as local
         # variables, so both kinds represent a parameter in jazzy.
@@ -72,6 +90,62 @@ module Jazzy
       end
 
       TYPES = {
+        # Objective-C
+
+        'sourcekitten.source.lang.objc.decl.category' => {
+          jazzy: 'Category',
+          dash: 'Extension',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.class' => {
+          jazzy: 'Class',
+          dash: 'Class',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.constant' => {
+          jazzy: 'Constant',
+          dash: 'Constant',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.enum' => {
+          jazzy: 'Enum',
+          dash: 'Enum',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.enumcase' => {
+          jazzy: 'Enum Case',
+          dash: 'Case',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.initializer' => {
+          jazzy: 'Initializer',
+          dash: 'Initializer',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.method.class' => {
+          jazzy: 'Class Method',
+          dash: 'Method',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.method.instance' => {
+          jazzy: 'Instance Method',
+          dash: 'Method',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.property' => {
+          jazzy: 'Property',
+          dash: 'Property',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.protocol' => {
+          jazzy: 'Protocol',
+          dash: 'Protocol',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.typedef' => {
+          jazzy: 'Type Definition',
+          dash: 'Alias',
+        }.freeze,
+        'sourcekitten.source.lang.objc.mark' => {
+          jazzy: 'Mark',
+          dash: 'Mark',
+        }.freeze,
+        'sourcekitten.source.lang.objc.decl.function' => {
+          jazzy: 'Function',
+          dash: 'Function',
+        }.freeze,
+
+        # Swift
         'source.lang.swift.decl.function.accessor.address' => {
           jazzy: 'Address Accessor',
           dash: 'Function',