jazzy 0.14.4 → 0.15.0

data/lib/jazzy/config.rb

@@ -13,16 +13,17 @@ module Jazzy
     # rubocop:disable Naming/AccessorMethodName
     class Attribute
       attr_reader :name, :description, :command_line, :config_file_key,
-                  :default, :parse
+                  :default, :parse, :per_module
 
       def initialize(name, description: nil, command_line: nil,
-                     default: nil, parse: ->(x) { x })
+                     default: nil, parse: ->(x) { x }, per_module: false)
         @name = name.to_s
         @description = Array(description)
         @command_line = Array(command_line)
         @default = default
         @parse = parse
         @config_file_key = full_command_line_name || @name
+        @per_module = per_module
       end
 
       def get(config)
@@ -134,22 +135,26 @@ module Jazzy
     config_attr :objc_mode,
       command_line: '--[no-]objc',
       description: 'Generate docs for Objective-C.',
-      default: false
+      default: false,
+      per_module: true
 
     config_attr :umbrella_header,
       command_line: '--umbrella-header PATH',
       description: 'Umbrella header for your Objective-C framework.',
-      parse: ->(uh) { expand_path(uh) }
+      parse: ->(uh) { expand_path(uh) },
+      per_module: true
 
     config_attr :framework_root,
       command_line: '--framework-root PATH',
       description: 'The root path to your Objective-C framework.',
-      parse: ->(fr) { expand_path(fr) }
+      parse: ->(fr) { expand_path(fr) },
+      per_module: true
 
     config_attr :sdk,
       command_line: '--sdk [iphone|watch|appletv][os|simulator]|macosx',
       description: 'The SDK for which your code should be built.',
-      default: 'macosx'
+      default: 'macosx',
+      per_module: true
 
     config_attr :hide_declarations,
       command_line: '--hide-declarations [objc|swift] ',
@@ -175,6 +180,13 @@ module Jazzy
       command_line: ['-b', '--build-tool-arguments arg1,arg2,…argN', Array],
       description: 'Arguments to forward to xcodebuild, swift build, or ' \
         'sourcekitten.',
+      default: [],
+      per_module: true
+
+    config_attr :modules,
+      command_line: ['--modules Mod1,Mod2,…ModN', Array],
+      description: 'List of modules to document.  Use the config file to set per-module ' \
+        "build flags, see 'Documenting multiple modules' in the README.",
       default: []
 
     alias_config_attr :xcodebuild_arguments, :build_tool_arguments,
@@ -185,19 +197,23 @@ module Jazzy
       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) } }
+      parse: ->(paths) { [paths].flatten.map { |path| expand_path(path) } },
+      default: [],
+      per_module: true
 
     config_attr :source_directory,
       command_line: '--source-directory DIRPATH',
       description: 'The directory that contains the source to be documented',
       default: Pathname.pwd,
-      parse: ->(sd) { expand_path(sd) }
+      parse: ->(sd) { expand_path(sd) },
+      per_module: true
 
     config_attr :symbolgraph_directory,
       command_line: '--symbolgraph-directory DIRPATH',
       description: 'A directory containing a set of Swift Symbolgraph files ' \
         'representing the module to be documented',
-      parse: ->(sd) { expand_path(sd) }
+      parse: ->(sd) { expand_path(sd) },
+      per_module: true
 
     config_attr :excluded_files,
       command_line: ['-e', '--exclude filepath1,filepath2,…filepathN', Array],
@@ -261,7 +277,8 @@ module Jazzy
     config_attr :module_name,
       command_line: ['-m', '--module MODULE_NAME'],
       description: 'Name of module being documented. (e.g. RealmSwift)',
-      default: ''
+      default: '',
+      per_module: true
 
     config_attr :version,
       command_line: '--module-version VERSION',
@@ -284,6 +301,10 @@ module Jazzy
       description: 'The path to a markdown README file',
       parse: ->(rp) { expand_path(rp) }
 
+    config_attr :readme_title,
+      command_line: '--readme-title TITLE',
+      description: 'The title for the README in the generated documentation'
+
     config_attr :documentation_glob,
       command_line: '--documentation GLOB',
       description: 'Glob that matches available documentation',
@@ -317,6 +338,13 @@ module Jazzy
       command_line: '--docset-path DIRPATH',
       description: 'The relative path for the generated docset'
 
+    config_attr :docset_title,
+      command_line: '--docset-title TITLE',
+      description: 'The title of the generated docset.  A simplified version ' \
+        'is used for the filenames associated with the docset.  If the ' \
+        'option is not set then the name of the module being documented is ' \
+        'used as the docset title.'
+
     # ──────── URLs ────────
 
     config_attr :root_url,
@@ -488,6 +516,23 @@ module Jazzy
         '--min-acl is set to `public` or `open`.',
       default: false
 
+    MERGE_MODULES = %w[all extensions none].freeze
+
+    config_attr :merge_modules,
+      command_line: "--merge-modules #{MERGE_MODULES.join(' | ')}",
+      description: 'Control how to display declarations from multiple ' \
+        'modules.  `all`, the default, places all declarations of the ' \
+        "same kind together.  `none` keeps each module's declarations " \
+        'separate.  `extensions` is like `none` but merges ' \
+        'cross-module extensions into their extended type.',
+      default: 'all',
+      parse: ->(merge) do
+        return merge.to_sym if MERGE_MODULES.include?(merge)
+
+        raise "Unsupported merge_modules #{merge}, " \
+          "supported values: #{MERGE_MODULES.join(', ')}"
+      end
+
     # rubocop:enable Layout/ArgumentAlignment
 
     def initialize
@@ -507,12 +552,7 @@ module Jazzy
       config.parse_config_file
       PodspecDocumenter.apply_config_defaults(config.podspec, config)
 
-      if config.root_url
-        config.dash_url ||= URI.join(
-          config.root_url,
-          "docsets/#{config.module_name}.xml",
-        )
-      end
+      config.set_module_configs
 
       config.validate
 
@@ -569,11 +609,13 @@ module Jazzy
       puts "Using config file #{config_path}"
       config_file = read_config_file(config_path)
 
-      attrs_by_conf_key, attrs_by_name = %i[config_file_key name].map do |prop|
-        self.class.all_config_attrs.group_by(&prop)
-      end
+      attrs_by_conf_key, attrs_by_name = grouped_attributes
 
-      config_file.each do |key, value|
+      parse_config_hash(config_file, attrs_by_conf_key, attrs_by_name)
+    end
+
+    def parse_config_hash(hash, attrs_by_conf_key, attrs_by_name, override: false)
+      hash.each do |key, value|
         unless attr = attrs_by_conf_key[key]
           message = "Unknown config file attribute #{key.inspect}"
           if matching_name = attrs_by_name[key]
@@ -583,11 +625,19 @@ module Jazzy
           warning message
           next
         end
-
-        attr.first.set_if_unconfigured(self, value)
+        setter = override ? :set : :set_if_unconfigured
+        attr.first.method(setter).call(self, value)
       end
+    end
 
-      self.base_path = nil
+    # Find keyed versions of the attributes, by config file key and then name-in-code
+    # Optional block allows filtering/overriding of attribute list.
+    def grouped_attributes
+      attrs = self.class.all_config_attrs
+      attrs = yield attrs if block_given?
+      %i[config_file_key name].map do |property|
+        attrs.group_by(&property)
+      end
     end
 
     def validate
@@ -598,6 +648,19 @@ module Jazzy
           '`source_host_url` or `source_host_files_url`.'
       end
 
+      if modules_configured && module_name_configured
+        raise 'Options `modules` and `module` are both set which is not supported. ' \
+          'To document multiple modules, use just `modules`.'
+      end
+
+      if modules_configured && podspec_configured
+        raise 'Options `modules` and `podspec` are both set which is not supported.'
+      end
+
+      module_configs.each(&:validate_module)
+    end
+
+    def validate_module
       if objc_mode &&
          build_tool_arguments_configured &&
          (framework_root_configured || umbrella_header_configured)
@@ -608,6 +671,76 @@ module Jazzy
 
     # rubocop:enable Metrics/MethodLength
 
+    # Module Configs
+    #
+    # The user can enter module information in three different ways.  This
+    # consolidates them into one view for the rest of the code.
+    #
+    # 1) Single module, back-compatible
+    #    --module Foo etc etc (or not given at all)
+    #
+    # 2) Multiple modules, simple, sharing build params
+    #    --modules Foo,Bar,Baz --source-directory Xyz
+    #
+    # 3) Multiple modules, custom, different build params but
+    #    inheriting others from the top level.
+    #    This is config-file only.
+    #    - modules
+    #      - module: Foo
+    #        source_directory: Xyz
+    #        build_tool_arguments: [a, b, c]
+    #
+    # After this we're left with `config.module_configs` that is an
+    # array of `Config` objects.
+
+    attr_reader :module_configs
+    attr_reader :module_names
+
+    def set_module_configs
+      @module_configs = parse_module_configs
+      @module_names = module_configs.map(&:module_name)
+      @module_names_set = Set.new(module_names)
+    end
+
+    def module_name?(name)
+      @module_names_set.include?(name)
+    end
+
+    def multiple_modules?
+      @module_names.count > 1
+    end
+
+    def parse_module_configs
+      return [self] unless modules_configured
+
+      raise 'Config file key `modules` must be an array' unless modules.is_a?(Array)
+
+      if modules.first.is_a?(String)
+        # Massage format (2) into (3)
+        self.modules = modules.map { { 'module' => _1 } }
+      end
+
+      # Allow per-module overrides of only some config options
+      attrs_by_conf_key, attrs_by_name =
+        grouped_attributes { _1.select(&:per_module) }
+
+      modules.map do |module_hash|
+        mod_name = module_hash['module'] || ''
+        raise 'Missing `modules.module` config key' if mod_name.empty?
+
+        dup.tap do |module_config|
+          module_config.parse_config_hash(
+            module_hash, attrs_by_conf_key, attrs_by_name, override: true
+          )
+        end
+      end
+    end
+
+    # For podspec query
+    def module_name_known?
+      module_name_configured || modules_configured
+    end
+
     def locate_config_file
       return config_file if config_file
 
@@ -615,7 +748,6 @@ module Jazzy
         candidate = dir.join('.jazzy.yaml')
         return candidate if candidate.exist?
       end
-
       nil
     end
 

data/lib/jazzy/doc.rb

@@ -48,9 +48,9 @@ module Jazzy
       elsif config.version_configured
         # Fake version for integration tests
         version = ENV['JAZZY_FAKE_MODULE_VERSION'] || config.version
-        "#{config.module_name} #{version} Docs"
+        "#{config.module_configs.first.module_name} #{version} Docs"
       else
-        "#{config.module_name} Docs"
+        "#{config.module_configs.first.module_name} Docs"
       end
     end
 

data/lib/jazzy/doc_builder.rb

@@ -67,32 +67,32 @@ module Jazzy
 
     # Build documentation from the given options
     # @param [Config] options
-    # @return [SourceModule] the documented source module
     def self.build(options)
-      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)
-      elsif options.swift_build_tool == :symbolgraph
-        stdout = SymbolGraph.build(options)
-      else
-        stdout = Dir.chdir(options.source_directory) do
-          arguments = SourceKitten.arguments_from_options(options)
-          SourceKitten.run_sourcekitten(arguments)
+      module_jsons = options.module_configs.map do |module_config|
+        if module_config.podspec_configured
+          # Config#validate guarantees not multi-module here
+          pod_documenter = PodspecDocumenter.new(options.podspec)
+          pod_documenter.sourcekitten_output(options)
+        elsif !module_config.sourcekitten_sourcefile.empty?
+          "[#{module_config.sourcekitten_sourcefile.map(&:read).join(',')}]"
+        elsif module_config.swift_build_tool == :symbolgraph
+          SymbolGraph.build(module_config)
+        else
+          Dir.chdir(module_config.source_directory) do
+            arguments = SourceKitten.arguments_from_options(module_config)
+            SourceKitten.run_sourcekitten(arguments)
+          end
         end
       end
 
-      build_docs_for_sourcekitten_output(stdout, options)
+      build_docs_for_sourcekitten_output(module_jsons, options)
     end
 
     # Build & write HTML docs to disk from structured docs array
     # @param [String] output_dir Root directory to write docs
-    # @param [Array] docs Array of structured docs
-    # @param [Config] options Build options
-    # @param [Array] doc_structure @see #doc_structure_for_docs
-    def self.build_docs(output_dir, docs, source_module)
-      each_doc(output_dir, docs) do |doc, path|
+    # @param [SourceModule] source_module All info to generate docs
+    def self.build_docs(output_dir, source_module)
+      each_doc(output_dir, source_module.docs) do |doc, path|
         prepare_output_dir(path.parent, false)
         depth = path.relative_path_from(output_dir).each_filename.count - 1
         path_to_root = '../' * depth
@@ -124,10 +124,13 @@ module Jazzy
 
       docs << SourceDocument.make_index(options.readme_path)
 
-      source_module = SourceModule.new(options, docs, structure, coverage)
-
       output_dir = options.output
-      build_docs(output_dir, source_module.docs, source_module)
+
+      docset_builder = DocsetBuilder.new(output_dir)
+
+      source_module = SourceModule.new(docs, structure, coverage, docset_builder)
+
+      build_docs(output_dir, source_module)
 
       unless options.disable_search
         warn 'building search index'
@@ -137,7 +140,7 @@ module Jazzy
       copy_extensions(source_module, output_dir)
       copy_theme_assets(output_dir)
 
-      DocsetBuilder.new(output_dir, source_module).build!
+      docset_builder.build!(source_module.all_declarations)
 
       generate_badge(source_module.doc_coverage, options)
 
@@ -148,14 +151,12 @@ module Jazzy
     end
 
     # Build docs given sourcekitten output
-    # @param [String] sourcekitten_output Output of sourcekitten command
+    # @param [Array<String>] sourcekitten_output Output of sourcekitten command for each module
     # @param [Config] options Build options
-    # @return [SourceModule] the documented source module
     def self.build_docs_for_sourcekitten_output(sourcekitten_output, options)
       (docs, stats) = SourceKitten.parse(
         sourcekitten_output,
-        options.min_acl,
-        options.skip_undocumented,
+        options,
         DocumentationGenerator.source_docs,
       )
 
@@ -249,7 +250,8 @@ module Jazzy
         doc[:doc_coverage] = source_module.doc_coverage unless
           Config.instance.hide_documentation_coverage
         doc[:structure] = source_module.doc_structure
-        doc[:module_name] = source_module.name
+        doc[:readme_title] = source_module.readme_title
+        doc[:module_name] = doc[:readme_title]
         doc[:author_name] = source_module.author_name
         if source_host = source_module.host
           doc[:source_host_name] = source_host.name
@@ -259,7 +261,8 @@ module Jazzy
           doc[:github_url] = doc[:source_host_url]
           doc[:github_token_url] = doc[:source_host_item_url]
         end
-        doc[:dash_url] = source_module.dash_url
+        doc[:dash_url] = source_module.dash_feed_url
+        doc[:breadcrumbs] = make_breadcrumbs(doc_model)
       end
     end
 
@@ -269,7 +272,7 @@ module Jazzy
     # @param [String] path_to_root
     def self.document_markdown(source_module, doc_model, path_to_root)
       doc = new_document(source_module, doc_model)
-      name = doc_model.name == 'index' ? source_module.name : doc_model.name
+      name = doc_model.readme? ? source_module.readme_title : doc_model.name
       doc[:name] = name
       doc[:overview] = render(doc_model, doc_model.content(source_module))
       doc[:path_to_root] = path_to_root
@@ -447,5 +450,28 @@ module Jazzy
       doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
     end
     # rubocop:enable Metrics/MethodLength
+
+    # Breadcrumbs for a page - doesn't include the top 'readme' crumb
+    def self.make_breadcrumbs(doc_model)
+      return [] if doc_model.readme?
+
+      docs_path = doc_model.docs_path
+      breadcrumbs = docs_path.map do |doc|
+        {
+          name: doc.name,
+          url: doc.url,
+          last: doc == doc_model,
+        }
+      end
+
+      return breadcrumbs if breadcrumbs.count == 1
+
+      # Add the module name to the outer type if not clear from context
+      if docs_path[1].ambiguous_module_name?(docs_path[0].name)
+        breadcrumbs[1][:name] = docs_path[1].fully_qualified_module_name
+      end
+
+      breadcrumbs
+    end
   end
 end

data/lib/jazzy/doc_index.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Jazzy
+  # This class stores an index of symbol names for doing name lookup
+  # when resolving custom categories and autolinks.
+  class DocIndex
+    # A node in the index tree.  The root has no decl; its children are
+    # per-module indexed by module names.  The second level, where each
+    # scope is a module, also has no decl; its children are scopes, one
+    # for each top-level decl in the module.  From the third level onwards
+    # the decl is valid.
+    class Scope
+      attr_reader :decl # SourceDeclaration
+      attr_reader :children # String:Scope
+
+      def initialize(decl, children)
+        @decl = decl
+        @children = children
+      end
+
+      def self.new_root(module_decls)
+        new(nil,
+            module_decls.transform_values do |decls|
+              Scope.new_decl(nil, decls)
+            end)
+      end
+
+      # Decl names in a scope are usually unique.  The exceptions
+      # are (1) methods and (2) typealias+extension, which historically
+      # jazzy does not merge.  The logic here and in `merge()` below
+      # preserves the historical ambiguity-resolution of (1) and tries
+      # to do the best for (2).
+      def self.new_decl(decl, child_decls)
+        child_scopes = {}
+        child_decls.flat_map do |child_decl|
+          child_scope = Scope.new_decl(child_decl, child_decl.children)
+          child_decl.index_names.map do |name|
+            if curr = child_scopes[name]
+              curr.merge(child_scope)
+            else
+              child_scopes[name] = child_scope
+            end
+          end
+        end
+        new(decl, child_scopes)
+      end
+
+      def merge(new_scope)
+        return unless type = decl&.type
+        return unless new_type = new_scope.decl&.type
+
+        if type.swift_typealias? && new_type.swift_extension?
+          @children = new_scope.children
+        elsif type.swift_extension? && new_type.swift_typealias?
+          @decl = new_scope.decl
+        end
+      end
+
+      # Lookup of a name like `Mod.Type.method(arg:)` requires passing
+      # an array of name 'parts' eg. ['Mod', 'Type', 'method(arg:)'].
+      def lookup(parts)
+        return decl if parts.empty?
+
+        children[parts.first]&.lookup(parts[1...])
+      end
+
+      # Get an array of scopes matching the name parts.
+      def lookup_path(parts)
+        [self] +
+          (children[parts.first]&.lookup_path(parts[1...]) || [])
+      end
+    end
+
+    attr_reader :root_scope
+
+    def initialize(all_decls)
+      @root_scope = Scope.new_root(all_decls.group_by(&:module_name))
+    end
+
+    # Look up a name and return the matching SourceDeclaration or nil.
+    #
+    # `context` is an optional SourceDeclaration indicating where the text
+    # was found, affects name resolution - see `lookup_context()` below.
+    def lookup(name, context = nil)
+      lookup_name = LookupName.new(name)
+
+      return lookup_fully_qualified(lookup_name) if lookup_name.fully_qualified?
+      return lookup_guess(lookup_name) if context.nil?
+
+      lookup_context(lookup_name, context)
+    end
+
+    private
+
+    # Look up a fully-qualified name, ie. it starts with the module name.
+    def lookup_fully_qualified(lookup_name)
+      root_scope.lookup(lookup_name.parts)
+    end
+
+    # Look up a top-level name best-effort, searching for a module that
+    # has it before trying the first name-part as a module name.
+    def lookup_guess(lookup_name)
+      root_scope.children.each_value do |module_scope|
+        if result = module_scope.lookup(lookup_name.parts)
+          return result
+        end
+      end
+
+      lookup_fully_qualified(lookup_name)
+    end
+
+    # Look up a name from a declaration context, approximately how
+    # Swift resolves names.
+    #
+    # 1 - try and resolve with a common prefix, eg. 'B' from 'T.A'
+    #     can match 'T.B', or 'R' from 'S.T.A' can match 'S.R'.
+    # 2 - try and resolve as a top-level symbol from a different module
+    # 3 - (affordance for docs writers) resolve as a child of the context,
+    #     eg. 'B' from 'T.A' can match 'T.A.B' *only if* (1,2) fail.
+    #     Currently disabled for Swift for back-compatibility.
+    def lookup_context(lookup_name, context)
+      context_scope_path =
+        root_scope.lookup_path(context.fully_qualified_module_name_parts)
+
+      context_scope = context_scope_path.pop
+      context_scope_path.reverse.each do |scope|
+        if decl = scope.lookup(lookup_name.parts)
+          return decl
+        end
+      end
+
+      lookup_guess(lookup_name) ||
+        (lookup_name.objc? && context_scope.lookup(lookup_name.parts))
+    end
+
+    # Helper for name lookup, really a cache for information as we
+    # try various strategies.
+    class LookupName
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def fully_qualified?
+        name.start_with?('/')
+      end
+
+      def objc?
+        name.start_with?('-', '+')
+      end
+
+      def parts
+        @parts ||= find_parts
+      end
+
+      private
+
+      # Turn a name as written into a list of components to
+      # be matched.
+      # Swift: Strip out odd characters and split
+      # ObjC: Compound names look like '+[Class(Category) method:]'
+      #       and need to become ['Class(Category)', '+method:']
+      def find_parts
+        if name =~ /([+-])\[(\w+(?: ?\(\w+\))?) ([\w:]+)\]/
+          [Regexp.last_match[2],
+           Regexp.last_match[1] + Regexp.last_match[3]]
+        else
+          name
+            .sub(%r{^[@\/]}, '') # ignore custom attribute reference, fully-qualified
+            .gsub(/<.*?>/, '') # remove generic parameters
+            .split(%r{(?<!\.)[/.](?!\.)}) # dot or slash, but not '...'
+            .reject(&:empty?)
+        end
+      end
+    end
+  end
+
+  class SourceDeclaration
+    # Names for a symbol.  Permits function parameters to be omitted.
+    def index_names
+      [name, name.sub(/\(.*\)/, '(...)')].uniq
+    end
+  end
+end

data/lib/jazzy/docset_builder/info_plist.mustache

@@ -3,7 +3,7 @@
 <plist version="1.0">
   <dict>
     <key>CFBundleIdentifier</key>
-      <string>com.jazzy.{{lowercase_name}}</string>
+      <string>com.jazzy.{{lowercase_safe_name}}</string>
     <key>CFBundleName</key>
       <string>{{name}}</string>
     <key>DocSetPlatformFamily</key>