jazzy 0.14.4 → 0.15.0

data/lib/jazzy/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jazzy
-  VERSION = '0.14.4' unless defined? Jazzy::VERSION
+  VERSION = '0.15.0' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/grouper.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Jazzy
+  # This module deals with arranging top-level declarations and guides into
+  # groups automatically and/or using a custom list.
+  module Grouper
+    extend Config::Mixin
+
+    # Group root-level docs by custom categories (if any) and type or module
+    def self.group_docs(docs, doc_index)
+      custom_categories, docs = group_custom_categories(docs, doc_index)
+      unlisted_prefix = config.custom_categories_unlisted_prefix
+      type_category_prefix = custom_categories.any? ? unlisted_prefix : ''
+      all_categories =
+        custom_categories +
+        if config.merge_modules == :all
+          group_docs_by_type(docs, type_category_prefix)
+        else
+          group_docs_by_module(docs, type_category_prefix)
+        end
+      merge_consecutive_marks(all_categories)
+    end
+
+    # Group root-level docs by type
+    def self.group_docs_by_type(docs, type_category_prefix)
+      type_groups = SourceDeclaration::Type.all.map do |type|
+        children, docs = docs.partition { _1.type == type }
+        make_type_group(children, type, type_category_prefix)
+      end
+      merge_categories(type_groups.compact) + docs
+    end
+
+    # Group root-level docs by module name
+    def self.group_docs_by_module(docs, type_category_prefix)
+      guide_categories, docs = group_guides(docs, type_category_prefix)
+
+      module_categories = docs
+        .group_by(&:doc_module_name)
+        .map do |name, module_docs|
+          make_group(
+            module_docs,
+            name,
+            "The following declarations are provided by module #{name}.",
+          )
+        end
+
+      guide_categories + module_categories
+    end
+
+    def self.group_custom_categories(docs, doc_index)
+      group = config.custom_categories.map do |category|
+        children = category['children'].filter_map do |name|
+          unless doc = doc_index.lookup(name)
+            warn 'WARNING: No documented top-level declarations match ' \
+              "name \"#{name}\" specified in categories file"
+            next nil
+          end
+
+          unless doc.parent_in_code.nil?
+            warn "WARNING: Declaration \"#{doc.fully_qualified_module_name}\" " \
+              'specified in categories file exists but is not top-level and ' \
+              'cannot be included here'
+            next nil
+          end
+
+          docs.delete(doc)
+        end
+        # Category config overrides alphabetization
+        children.each.with_index { |child, i| child.nav_order = i }
+        make_group(children, category['name'], '')
+      end
+      [group.compact, docs]
+    end
+
+    def self.group_guides(docs, prefix)
+      guides, others = docs.partition { _1.type.markdown? }
+      return [[], others] unless guides.any?
+
+      [[make_type_group(guides, guides.first.type, prefix)], others]
+    end
+
+    def self.make_type_group(docs, type, type_category_prefix)
+      make_group(
+        docs,
+        type_category_prefix + type.plural_name,
+        "The following #{type.plural_name.downcase} are available globally.",
+        type_category_prefix + type.plural_url_name,
+      )
+    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 { _1.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! { _1.name.empty? }
+      unless group.empty?
+        SourceDeclaration.new.tap do |sd|
+          sd.type     = SourceDeclaration::Type.overview
+          sd.name     = name
+          sd.url_name = url_name
+          sd.abstract = Markdown.render(abstract)
+          sd.children = group
+        end
+      end
+    end
+
+    # Merge consecutive sections with the same mark into one section
+    # Needed because of pulling various decls into groups
+    def self.merge_consecutive_marks(docs)
+      prev_mark = nil
+      docs.each do |doc|
+        if prev_mark&.can_merge?(doc.mark)
+          doc.mark = prev_mark
+        end
+        prev_mark = doc.mark
+        merge_consecutive_marks(doc.children)
+      end
+    end
+  end
+end

data/lib/jazzy/podspec_documenter.rb

@@ -52,7 +52,7 @@ module Jazzy
         config.author_name = author_name(podspec)
         config.author_name_configured = true
       end
-      unless config.module_name_configured
+      unless config.module_name_known?
         config.module_name = podspec.module_name
         config.module_name_configured = true
       end

data/lib/jazzy/source_declaration/type.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'active_support'
 require 'active_support/inflector'
 
 module Jazzy
@@ -163,8 +164,14 @@ module Jazzy
         kind == 'sourcekitten.source.lang.objc.decl.unexposed'
       end
 
+      OVERVIEW_KIND = 'Overview'
+
       def self.overview
-        Type.new('Overview')
+        Type.new(OVERVIEW_KIND)
+      end
+
+      def overview?
+        kind == OVERVIEW_KIND
       end
 
       MARKDOWN_KIND = 'document.markdown'
@@ -193,7 +200,8 @@ module Jazzy
           dash: 'Guide',
         }.freeze,
 
-        'Overview' => {
+        # Group/Overview
+        OVERVIEW_KIND => {
           jazzy: nil,
           dash: 'Section',
         }.freeze,

data/lib/jazzy/source_declaration.rb

@@ -62,6 +62,7 @@ module Jazzy
       end
     end
 
+    # 'OuterType.NestedType.method(arg:)'
     def fully_qualified_name
       namespace_path.map(&:name).join('.')
     end
@@ -74,6 +75,21 @@ module Jazzy
                                .join('(?:<.*?>)?\.'))
     end
 
+    def fully_qualified_module_name_parts
+      path = namespace_path
+      path.map(&:name).prepend(path.first.module_name).compact
+    end
+
+    # 'MyModule.OuterType.NestedType.method(arg:)'
+    def fully_qualified_module_name
+      fully_qualified_module_name_parts.join('.')
+    end
+
+    # List of doc_parent decls, .last is self
+    def docs_path
+      (parent_in_docs&.docs_path || []) + [self]
+    end
+
     # If this declaration is an objc category, returns an array with the name
     # of the extended objc class and the category name itself, i.e.
     # ["NSString", "MyMethods"], nil otherwise.
@@ -114,7 +130,7 @@ module Jazzy
     attr_accessor :column
     attr_accessor :usr
     attr_accessor :type_usr
-    attr_accessor :modulename
+    attr_accessor :module_name
     attr_accessor :name
     attr_accessor :objc_name
     attr_accessor :declaration
@@ -140,6 +156,11 @@ module Jazzy
     attr_accessor :inherited_types
     attr_accessor :async
 
+    # The name of the module being documented that contains this
+    # declaration.  Only different from module_name when this is
+    # an extension of a type from another module.  Nil for guides.
+    attr_accessor :doc_module_name
+
     def usage_discouraged?
       unavailable || deprecated
     end
@@ -183,20 +204,60 @@ module Jazzy
       inherited_types.any? { |t| !unwanted.include?(t) }
     end
 
-    # Pre-Swift 5.6: SourceKit only sets modulename for imported modules
-    # Swift 5.6+: modulename is always set
+    # Pre-Swift 5.6: SourceKit only sets module_name for imported modules
+    # Swift 5.6+: module_name is always set
     def type_from_doc_module?
       !type.extension? ||
         (swift? && usr &&
-          (modulename.nil? || modulename == Config.instance.module_name))
+          (module_name.nil? || module_name == doc_module_name))
+    end
+
+    # Don't ask the user to write documentation for types being extended
+    # from other modules.  Compile errors leave no docs and a `nil` USR.
+    def mark_undocumented?
+      !swift? || (usr && !extension_of_external_type?)
+    end
+
+    def extension_of_external_type?
+      !module_name.nil? &&
+        !Config.instance.module_name?(module_name)
+    end
+
+    # Is it unclear from context what module the (top-level) decl is from?
+    def ambiguous_module_name?(group_name)
+      extension_of_external_type? ||
+        (Config.instance.multiple_modules? &&
+          !module_name.nil? &&
+          group_name != module_name)
+    end
+
+    # Does the user need help understanding how to get this declaration?
+    def need_doc_module_note?
+      return false unless Config.instance.multiple_modules?
+      return false if docs_path.first.name == doc_module_name
+
+      if parent_in_code.nil?
+        # Top-level decls with no page of their own
+        !render_as_page?
+      else
+        # Members added by extension
+        parent_in_code.module_name != doc_module_name
+      end
     end
 
     # Info text for contents page by collapsed item name
     def declaration_note
-      notes = [default_impl_abstract ? 'default implementation' : nil,
-               from_protocol_extension ? 'extension method' : nil,
-               async ? 'asynchronous' : nil].compact
-      notes.join(', ').humanize unless notes.empty?
+      notes = [
+        default_impl_abstract ? 'default implementation' : nil,
+        from_protocol_extension ? 'extension method' : nil,
+        async ? 'asynchronous' : nil,
+        need_doc_module_note? ? "from #{doc_module_name}" : nil,
+      ].compact
+      notes.join(', ').upcase_first unless notes.empty?
+    end
+
+    def readme?
+      false
     end
 
     def alternative_abstract

data/lib/jazzy/source_document.rb

@@ -27,6 +27,10 @@ module Jazzy
       end
     end
 
+    def readme?
+      url == 'index.html'
+    end
+
     def render_as_page?
       true
     end
@@ -89,7 +93,7 @@ pod '#{podspec.name}'
         README
       else
         <<-README
-# #{source_module.name}
+# #{source_module.readme_title}
 
 ### Authors
 

data/lib/jazzy/source_module.rb

@@ -7,28 +7,30 @@ require 'jazzy/source_declaration'
 require 'jazzy/source_host'
 
 module Jazzy
+  # A cache of info that is common across all page templating, gathered
+  # from other parts of the program.
   class SourceModule
-    attr_accessor :name
+    include Config::Mixin
+
+    attr_accessor :readme_title
     attr_accessor :docs
     attr_accessor :doc_coverage
     attr_accessor :doc_structure
     attr_accessor :author_name
     attr_accessor :author_url
-    attr_accessor :dash_url
+    attr_accessor :dash_feed_url
     attr_accessor :host
 
-    def initialize(options, docs, doc_structure, doc_coverage)
+    def initialize(docs, doc_structure, doc_coverage, docset_builder)
       self.docs = docs
       self.doc_structure = doc_structure
       self.doc_coverage = doc_coverage
-      self.name = options.module_name
-      self.author_name = options.author_name
-      self.author_url = options.author_url
-      self.host = SourceHost.create(options)
-      return unless options.dash_url
-
-      self.dash_url =
-        "dash-feed://#{ERB::Util.url_encode(options.dash_url.to_s)}"
+      title = config.readme_title || config.module_names.first
+      self.readme_title = title.empty? ? 'Index' : title
+      self.author_name = config.author_name
+      self.author_url = config.author_url
+      self.host = SourceHost.create(config)
+      self.dash_feed_url = docset_builder.dash_feed_url
     end
 
     def all_declarations