jazzy 0.13.7 → 0.14.2

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 #-- Bootstrap --------------------------------------------------------------#
 
 desc 'Initializes your working copy to run the specs'
@@ -9,7 +11,7 @@ task :bootstrap do
     title 'Updating submodules'
     sh 'git submodule update --init --recursive'
   else
-    $stderr.puts "\033[0;31m" \
+    warn "\033[0;31m" \
       "[!] Please install the bundler gem manually:\n" \
       '    $ [sudo] gem install bundler' \
       "\e[0m"
@@ -95,7 +97,7 @@ begin
 
   desc 'Runs RuboCop linter on Ruby files'
   task :rubocop do
-    sh 'bundle exec rubocop lib spec'
+    sh 'bundle exec rubocop'
   end
 
   #-- SourceKitten -----------------------------------------------------------#
@@ -103,10 +105,12 @@ begin
   desc 'Vendors SourceKitten'
   task :sourcekitten do
     sk_dir = 'SourceKitten'
-    Dir.chdir(sk_dir) do
-      `swift build -c release`
+    bin_path = Dir.chdir(sk_dir) do
+      build_cmd = 'swift build -c release --arch arm64 --arch x86_64'
+      `#{build_cmd}`
+      `#{build_cmd} --show-bin-path`.chomp
     end
-    FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
+    FileUtils.cp_r "#{bin_path}/sourcekitten", 'bin'
   end
 
   #-- Theme Dependencies -----------------------------------------------------#
@@ -115,20 +119,20 @@ begin
     'jquery/dist/jquery.min.js' => [
       'themes/apple/assets/js',
       'themes/fullwidth/assets/js',
-      'themes/jony/assets/js'
+      'themes/jony/assets/js',
     ],
     'lunr/lunr.min.js' => [
       'themes/apple/assets/js',
-      'themes/fullwidth/assets/js'
+      'themes/fullwidth/assets/js',
     ],
     'corejs-typeahead/dist/typeahead.jquery.js' => [
       'themes/apple/assets/js',
-      'themes/fullwidth/assets/js'
+      'themes/fullwidth/assets/js',
     ],
     'katex/dist/katex.min.css' => ['extensions/katex/css'],
     'katex/dist/fonts' => ['extensions/katex/css'],
-    'katex/dist/katex.min.js' => ['extensions/katex/js']
-  }
+    'katex/dist/katex.min.js' => ['extensions/katex/js'],
+  }.freeze
 
   desc 'Copies theme dependencies (`npm update/install` by hand first)'
   task :theme_deps do
@@ -138,15 +142,14 @@ begin
       end
     end
   end
-
 rescue LoadError, NameError => e
-  $stderr.puts "\033[0;31m" \
+  warn "\033[0;31m" \
     '[!] Some Rake tasks haven been disabled because the environment' \
     ' couldn’t be loaded. Be sure to run `rake bootstrap` first.' \
     "\e[0m"
-  $stderr.puts e.message
-  $stderr.puts e.backtrace
-  $stderr.puts
+  warn e.message
+  warn e.backtrace
+  warn ''
 end
 
 #-- Helpers ------------------------------------------------------------------#

data/bin/jazzy

@@ -1,10 +1,11 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 if $PROGRAM_NAME == __FILE__ && !ENV['JAZZY_NO_BUNDLER']
-  ENV['BUNDLE_GEMFILE'] = File.expand_path('../../Gemfile', __FILE__)
+  ENV['BUNDLE_GEMFILE'] = File.expand_path('../Gemfile', __dir__)
   require 'rubygems'
   require 'bundler/setup'
-  $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 elsif ENV['JAZZY_NO_BUNDLER']
   require 'rubygems'
   gem 'jazzy'

data/jazzy.gemspec

@@ -1,4 +1,5 @@
 # coding: utf-8
+# frozen_string_literal: true
 
 require File.expand_path('lib/jazzy/gem_version.rb', File.dirname(__FILE__))
 
@@ -9,25 +10,27 @@ Gem::Specification.new do |spec|
   spec.email         = ['jp@jpsim.com']
   spec.summary       = 'Soulful docs for Swift & Objective-C.'
   spec.description   = 'Soulful docs for Swift & Objective-C. ' \
-                       "Run in your Xcode project's root directory for " \
-                       'instant HTML docs.'
+    "Run in your SPM or Xcode project's root directory for " \
+    'instant HTML docs.'
   spec.homepage      = 'https://github.com/realm/jazzy'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
-  spec.executables   << 'jazzy'
+  spec.executables << 'jazzy'
 
   spec.add_runtime_dependency 'cocoapods', '~> 1.5'
   spec.add_runtime_dependency 'mustache', '~> 1.1'
-  spec.add_runtime_dependency 'open4'
+  spec.add_runtime_dependency 'open4', '~> 1.3'
   spec.add_runtime_dependency 'redcarpet', '~> 3.4'
+  spec.add_runtime_dependency 'rexml', '~> 3.2'
   spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
   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'
+  spec.add_development_dependency 'bundler', '~> 2.1'
   spec.add_development_dependency 'rake', '~> 13.0'
 
-  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_ruby_version = '>= 2.6.3'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/jazzy/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'optparse'
 require 'pathname'
 require 'uri'
@@ -8,7 +10,7 @@ require 'jazzy/source_declaration/access_control_level'
 module Jazzy
   # rubocop:disable Metrics/ClassLength
   class Config
-    # rubocop:disable Style/AccessorMethodName
+    # rubocop:disable Naming/AccessorMethodName
     class Attribute
       attr_reader :name, :description, :command_line, :config_file_key,
                   :default, :parse
@@ -50,6 +52,7 @@ module Jazzy
 
       def attach_to_option_parser(config, opt)
         return if command_line.empty?
+
         opt.on(*command_line, *description) do |val|
           set(config, val)
         end
@@ -70,11 +73,12 @@ module Jazzy
         end
       end
     end
-    # rubocop:enable Style/AccessorMethodName
+    # rubocop:enable Naming/AccessorMethodName
 
     def self.config_attr(name, **opts)
       attr_accessor name
       attr_accessor "#{name}_configured"
+
       @all_config_attrs ||= []
       @all_config_attrs << Attribute.new(name, **opts)
     end
@@ -112,7 +116,7 @@ module Jazzy
 
     # ──────── Build ────────
 
-    # rubocop:disable Layout/AlignParameters
+    # rubocop:disable Layout/ArgumentAlignment
 
     config_attr :output,
       description: 'Folder to output the HTML docs to',
@@ -124,7 +128,7 @@ module Jazzy
       command_line: ['-c', '--[no-]clean'],
       description: ['Delete contents of output directory before running. ',
                     'WARNING: If --output is set to ~/Desktop, this will '\
-                    'delete the ~/Desktop directory.'],
+                      'delete the ~/Desktop directory.'],
       default: false
 
     config_attr :objc_mode,
@@ -150,10 +154,10 @@ module Jazzy
     config_attr :hide_declarations,
       command_line: '--hide-declarations [objc|swift] ',
       description: 'Hide declarations in the specified language. Given that ' \
-                   'generating Swift docs only generates Swift declarations, ' \
-                   'this is useful for hiding a specific interface for ' \
-                   'either Objective-C or mixed Objective-C and Swift ' \
-                   'projects.',
+        'generating Swift docs only generates Swift declarations, ' \
+        'this is useful for hiding a specific interface for ' \
+        'either Objective-C or mixed Objective-C and Swift ' \
+        'projects.',
       default: ''
 
     config_attr :keep_property_attributes,
@@ -170,7 +174,7 @@ module Jazzy
     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.',
+        'sourcekitten.',
       default: []
 
     alias_config_attr :xcodebuild_arguments, :build_tool_arguments,
@@ -189,10 +193,16 @@ module Jazzy
       default: Pathname.pwd,
       parse: ->(sd) { expand_path(sd) }
 
+    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) }
+
     config_attr :excluded_files,
       command_line: ['-e', '--exclude filepath1,filepath2,…filepathN', Array],
       description: 'Source file pathnames to be excluded from documentation. '\
-                   'Supports wildcards.',
+        'Supports wildcards.',
       default: [],
       parse: ->(files) do
         Array(files).map { |f| expand_glob_path(f).to_s }
@@ -201,7 +211,7 @@ module Jazzy
     config_attr :included_files,
       command_line: ['-i', '--include filepath1,filepath2,…filepathN', Array],
       description: 'Source file pathnames to be included in documentation. '\
-                   'Supports wildcards.',
+        'Supports wildcards.',
       default: [],
       parse: ->(files) do
         Array(files).map { |f| expand_glob_path(f).to_s }
@@ -213,8 +223,9 @@ module Jazzy
       parse: ->(v) do
         if v.to_s.empty?
           nil
+        elsif v.to_f < 2
+          raise 'jazzy only supports Swift 2.0 or later.'
         else
-          raise 'jazzy only supports Swift 2.0 or later.' if v.to_f < 2
           v
         end
       end
@@ -224,13 +235,14 @@ module Jazzy
     config_attr :swift_build_tool,
       command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
       description: 'Control whether Jazzy uses Swift Package Manager, '\
-                   'xcodebuild, or swift-symbolgraph to build the module '\
-                   'to be documented.  By default it uses xcodebuild if '\
-                   'there is a .xcodeproj file in the source directory.',
+        'xcodebuild, or swift-symbolgraph 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(', ')}"
+          "supported values: #{SWIFT_BUILD_TOOLS.join(', ')}"
       end
 
     # ──────── Metadata ────────
@@ -254,13 +266,13 @@ module Jazzy
     config_attr :version,
       command_line: '--module-version VERSION',
       description: 'Version string to use as part of the default docs '\
-                   'title and inside the docset.',
+        '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 generated from module name and version.',
       default: ''
 
     config_attr :copyright,
@@ -285,16 +297,16 @@ module Jazzy
     config_attr :podspec,
       command_line: '--podspec FILEPATH',
       description: 'A CocoaPods Podspec that describes the Swift library to '\
-                   'document',
+        'document',
       parse: ->(ps) { PodspecDocumenter.create_podspec(Pathname(ps)) if ps },
       default: Dir['*.podspec{,.json}'].first
 
     config_attr :pod_sources,
       command_line: ['--pod-sources url1,url2,…urlN', Array],
       description: 'A list of sources to find pod dependencies. Used only '\
-                   'with --podspec when the podspec contains references to '\
-                   'privately hosted pods. You must include the default pod '\
-                   'source if public pods are also used.',
+        'with --podspec when the podspec contains references to '\
+        'privately hosted pods. You must include the default pod '\
+        'source if public pods are also used.',
       default: []
 
     config_attr :docset_icon,
@@ -316,30 +328,56 @@ module Jazzy
     config_attr :dash_url,
       command_line: ['-d', '--dash_url URL'],
       description: 'Location of the dash XML feed '\
-                    'e.g. https://realm.io/docsets/realm.xml)',
+        'e.g. https://realm.io/docsets/realm.xml)',
       parse: ->(d) { URI(d) }
 
-    config_attr :github_url,
-      command_line: ['-g', '--github_url URL'],
-      description: 'GitHub URL of this project (e.g. '\
-                   'https://github.com/realm/realm-cocoa)',
+    SOURCE_HOSTS = %w[github gitlab bitbucket].freeze
+
+    config_attr :source_host,
+      command_line: "--source-host #{SOURCE_HOSTS.join(' | ')}",
+      description: ['The source-code hosting site to be linked from documentation.',
+                    'This setting affects the logo image and link format.',
+                    "Default: 'github'"],
+      default: 'github',
+      parse: ->(host) do
+        return host.to_sym if SOURCE_HOSTS.include?(host)
+
+        raise "Unsupported source_host '#{host}', "\
+          "supported values: #{SOURCE_HOSTS.join(', ')}"
+      end
+
+    config_attr :source_host_url,
+      command_line: ['--source-host-url URL'],
+      description: ["URL to link from the source host's logo.",
+                    'For example https://github.com/realm/realm-cocoa'],
       parse: ->(g) { URI(g) }
 
-    config_attr :github_file_prefix,
+    alias_config_attr :github_url, :source_host_url,
+      command_line: ['-g', '--github_url URL'],
+      description: 'Back-compatibility alias for source_host_url.'
+
+    config_attr :source_host_files_url,
+      command_line: '--source-host-files-url PREFIX',
+      description: [
+        "The base URL on the source host of the project's files, to link "\
+          'from individual declarations.',
+        'For example https://github.com/realm/realm-cocoa/tree/v0.87.1',
+      ]
+
+    alias_config_attr :github_file_prefix, :source_host_files_url,
       command_line: '--github-file-prefix PREFIX',
-      description: 'GitHub URL file prefix of this project (e.g. '\
-                   'https://github.com/realm/realm-cocoa/tree/v0.87.1)'
+      description: 'Back-compatibility alias for source_host_files_url'
 
     config_attr :docset_playground_url,
       command_line: '--docset-playground-url URL',
       description: 'URL of an interactive playground to demonstrate the '\
-                   'framework, linked to from the docset.'
+        'framework, linked to from the docset.'
 
     # ──────── Doc generation options ────────
     config_attr :disable_search,
       command_line: '--disable-search',
-      description: ['Avoid generating a search index. '\
-                    'Search is available in some themes.'],
+      description: 'Avoid generating a search index. '\
+        'Search is available in some themes.',
       default: false
 
     config_attr :skip_documentation,
@@ -359,7 +397,7 @@ module Jazzy
     config_attr :skip_undocumented,
       command_line: '--[no-]skip-undocumented',
       description: "Don't document declarations that have no documentation "\
-                   'comments.',
+        'comments.',
       default: false
 
     config_attr :hide_documentation_coverage,
@@ -368,22 +406,22 @@ module Jazzy
       default: false
 
     config_attr :custom_categories,
-      description: ['Custom navigation categories to replace the standard '\
-                    '“Classes, Protocols, etc.”', 'Types not explicitly named '\
-                    'in a custom category appear in generic groups at the end.',
-                    'Example: https://git.io/v4Bcp'],
+      description: 'Custom navigation categories to replace the standard '\
+        "'Classes', 'Protocols', etc. Types not explicitly named "\
+        'in a custom category appear in generic groups at the '\
+        'end.  Example: https://git.io/v4Bcp',
       default: []
 
     config_attr :custom_categories_unlisted_prefix,
       description: "Prefix for navigation section names that aren't "\
-                   'explicitly listed in `custom_categories`.',
+        'explicitly listed in `custom_categories`.',
       default: 'Other '
 
     config_attr :hide_unlisted_documentation,
       command_line: '--[no-]hide-unlisted-documentation',
       description: "Don't include documentation in the sidebar from the "\
-                   "`documentation` config value that aren't explicitly "\
-                   'listed in `custom_categories`.',
+        "`documentation` config value that aren't explicitly "\
+        'listed in `custom_categories`.',
       default: false
 
     config_attr :custom_head,
@@ -391,15 +429,15 @@ module Jazzy
       description: 'Custom HTML to inject into <head></head>.',
       default: ''
 
-    BUILTIN_THEME_DIR = Pathname(__FILE__).parent + 'themes'
+    BUILTIN_THEME_DIR = Pathname(__dir__) + 'themes'
     BUILTIN_THEMES = BUILTIN_THEME_DIR.children(false).map(&:to_s)
 
     config_attr :theme_directory,
       command_line: "--theme [#{BUILTIN_THEMES.join(' | ')} | DIRPATH]",
       description: "Which theme to use. Specify either 'apple' (default), "\
-                   'one of the other built-in theme names, or the path to '\
-                   'your mustache templates and other assets for a custom '\
-                   'theme.',
+        'one of the other built-in theme names, or the path to '\
+        'your mustache templates and other assets for a custom '\
+        'theme.',
       default: 'apple',
       parse: ->(t) do
         if BUILTIN_THEMES.include?(t)
@@ -412,9 +450,9 @@ module Jazzy
     config_attr :use_safe_filenames,
       command_line: '--use-safe-filenames',
       description: 'Replace unsafe characters in filenames with an encoded '\
-                   'representation. This will reduce human readability of '\
-                   'some URLs, but may be necessary for projects that '\
-                   'expose filename-unfriendly functions such as /(_:_:)',
+        'representation. This will reduce human readability of '\
+        'some URLs, but may be necessary for projects that '\
+        'expose filename-unfriendly functions such as /(_:_:)',
       default: false
 
     config_attr :template_directory,
@@ -434,17 +472,23 @@ module Jazzy
     config_attr :undocumented_text,
       command_line: '--undocumented-text UNDOCUMENTED_TEXT',
       description: 'Default text for undocumented symbols. The default '\
-                   'is "Undocumented", put "" if no text is required',
+        'is "Undocumented", put "" if no text is required',
       default: 'Undocumented'
 
     config_attr :separate_global_declarations,
       command_line: '--[no-]separate-global-declarations',
       description: 'Create separate pages for all global declarations '\
-                   "(classes, structures, enums etc.) even if they don't "\
-                   'have children.',
+        "(classes, structures, enums etc.) even if they don't "\
+        'have children.',
+      default: false
+
+    config_attr :include_spi_declarations,
+      command_line: '--[no-]include-spi-declarations',
+      description: 'Include Swift declarations marked `@_spi` even if '\
+        '--min-acl is set to `public` or `open`.',
       default: false
 
-    # rubocop:enable Style/AlignParameter
+    # rubocop:enable Layout/ArgumentAlignment
 
     def initialize
       self.class.all_config_attrs.each do |attr|
@@ -457,7 +501,6 @@ module Jazzy
       Doc.template_path = theme_directory + 'templates'
     end
 
-    # rubocop:disable Metrics/MethodLength
     def self.parse!
       config = new
       config.parse_command_line
@@ -471,9 +514,16 @@ module Jazzy
         )
       end
 
+      config.validate
+
       config
     end
 
+    def warning(message)
+      warn "WARNING: #{message}"
+    end
+
+    # rubocop:disable Metrics/MethodLength
     def parse_command_line
       OptionParser.new do |opt|
         opt.banner = 'Usage: jazzy'
@@ -485,7 +535,7 @@ module Jazzy
         end
 
         opt.on('-v', '--version', 'Print version number') do
-          puts 'jazzy version: ' + Jazzy::VERSION
+          puts "jazzy version: #{Jazzy::VERSION}"
           exit
         end
 
@@ -504,6 +554,10 @@ module Jazzy
           exit
         end
       end.parse!
+
+      unless ARGV.empty?
+        warning "Leftover unused command-line text: #{ARGV}"
+      end
     end
 
     def parse_config_file
@@ -521,13 +575,12 @@ module Jazzy
 
       config_file.each do |key, value|
         unless attr = attrs_by_conf_key[key]
-          message = "WARNING: Unknown config file attribute #{key.inspect}"
+          message = "Unknown config file attribute #{key.inspect}"
           if matching_name = attrs_by_name[key]
-            message << ' (Did you mean '
-            message << matching_name.first.config_file_key.inspect
-            message << '?)'
+            message +=
+              " (Did you mean #{matching_name.first.config_file_key.inspect}?)"
           end
-          warn message
+          warning message
           next
         end
 
@@ -537,6 +590,24 @@ module Jazzy
       self.base_path = nil
     end
 
+    def validate
+      if source_host_configured &&
+         source_host_url.nil? &&
+         source_host_files_url.nil?
+        warning 'Option `source_host` is set but has no effect without either '\
+          '`source_host_url` or `source_host_files_url`.'
+      end
+
+      if objc_mode &&
+         build_tool_arguments_configured &&
+         (framework_root_configured || umbrella_header_configured)
+        warning 'Option `build_tool_arguments` is set: values passed to '\
+          '`framework_root` or `umbrella_header` may be ignored.'
+      end
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
     def locate_config_file
       return config_file if config_file
 
@@ -550,15 +621,10 @@ module Jazzy
 
     def read_config_file(file)
       case File.extname(file)
-        when '.json'         then JSON.parse(File.read(file))
-        when '.yaml', '.yml' then
-          if YAML.respond_to?('safe_load') # ruby >= 2.1.0
-            YAML.safe_load(File.read(file))
-          else
-            # rubocop:disable Security/YAMLLoad
-            YAML.load(File.read(file))
-            # rubocop:enable Security/YAMLLoad
-          end
+        when '.json'
+          JSON.parse(File.read(file))
+        when '.yaml', '.yml'
+          YAML.safe_load(File.read(file))
         else raise "Config file must be .yaml or .json, but got #{file.inspect}"
       end
     end
@@ -575,7 +641,7 @@ module Jazzy
 
         The config file can be in YAML or JSON format. Available options are:
 
-        _EOS_
+      _EOS_
         .gsub(/^ +/, '')
 
       print_option_help

data/lib/jazzy/doc.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'date'
 require 'pathname'
 require 'mustache'
@@ -18,7 +20,7 @@ module Jazzy
         date = ENV['JAZZY_FAKE_DATE'] || DateTime.now.strftime('%Y-%m-%d')
         year = date[0..3]
         "© #{year} [#{config.author_name}](#{config.author_url}). " \
-        "All rights reserved. (Last updated: #{date})"
+          "All rights reserved. (Last updated: #{date})"
       )
       Markdown.render_copyright(copyright).chomp
     end