jazzy 0.13.4 → 0.14.0

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 -----------------------------------------------------------#
@@ -115,15 +117,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',
+    ],
+    'corejs-typeahead/dist/typeahead.jquery.js' => [
+      'themes/apple/assets/js',
+      'themes/fullwidth/assets/js',
     ],
-    'lunr/lunr.min.js' => ['themes/fullwidth/assets/js'],
-    'corejs-typeahead/dist/typeahead.jquery.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
@@ -133,15 +140,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,26 @@ 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 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'
 end

data/js/package-lock.json

@@ -1,39 +1,44 @@
 {
-  "name": "jazzy-js",
-  "version": "1.0.0",
-  "lockfileVersion": 1,
+  "lockfileVersion": 2,
   "requires": true,
-  "dependencies": {
-    "commander": {
-      "version": "2.20.3",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
-      "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ=="
+  "packages": {
+    "node_modules/commander": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-6.2.1.tgz",
+      "integrity": "sha512-U7VdrJFnJgo4xjrHpTzu0yrHPGImdsmD95ZlgYSEajAn2JKzDhDTPG9kBTefmObL2w/ngeZnilk+OV9CG3d7UA==",
+      "engines": {
+        "node": ">= 6"
+      }
     },
-    "corejs-typeahead": {
+    "node_modules/corejs-typeahead": {
       "version": "1.3.1",
       "resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.1.tgz",
       "integrity": "sha512-fyNlBNWJNL6EQUnJyAunEzBzRcwR2cEHtZXBi2pndHPOJ/wpOf3wbS+/Oh+kYYS5sKowQcs0LFwMSl6Y2Xeqkw==",
-      "requires": {
+      "dependencies": {
         "jquery": ">=1.11"
       }
     },
-    "jquery": {
-      "version": "3.5.1",
-      "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.5.1.tgz",
-      "integrity": "sha512-XwIBPqcMn57FxfT+Go5pzySnm4KWkT1Tv7gjrpT1srtf8Weynl6R273VJ5GjkRb51IzMp5nbaPjJXMWeju2MKg=="
+    "node_modules/jquery": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.6.0.tgz",
+      "integrity": "sha512-JVzAR/AjBvVt2BmYhxRCSYysDsPcssdmTFnzyLEts9qNwmjmu4JTAMYubEfwVOSwpQ1I1sKKFcxhZCI2buerfw=="
     },
-    "katex": {
-      "version": "0.11.1",
-      "resolved": "https://registry.npmjs.org/katex/-/katex-0.11.1.tgz",
-      "integrity": "sha512-5oANDICCTX0NqYIyAiFCCwjQ7ERu3DQG2JFHLbYOf+fXaMoH8eg/zOq5WSYJsKMi/QebW+Eh3gSM+oss1H/bww==",
-      "requires": {
-        "commander": "^2.19.0"
+    "node_modules/katex": {
+      "version": "0.13.5",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.13.5.tgz",
+      "integrity": "sha512-n2uEzFpNFUOAlWs0eCgmT82LQyP+BlS45yBgnLRqe+ENp3+FEM3lM+cJwZwwxxONFgayyq1fm6n+w35vo2MaUg==",
+      "dependencies": {
+        "commander": "^6.0.0"
+      },
+      "bin": {
+        "katex": "cli.js"
       }
     },
-    "lunr": {
-      "version": "2.3.8",
-      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.8.tgz",
-      "integrity": "sha512-oxMeX/Y35PNFuZoHp+jUj5OSEmLCaIH4KTFJh7a93cHBoFmpw2IoPs22VIz7vyO2YUnx2Tn9dzIwO2P/4quIRg=="
+    "node_modules/lunr": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
+      "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
     }
-  }
+  },
+  "dependencies": {}
 }

data/js/package.json

@@ -10,8 +10,8 @@
   "license": "MIT",
   "dependencies": {
     "corejs-typeahead": "^1.3.1",
-    "jquery": "^3.5.1",
-    "katex": "^0.11.1",
-    "lunr": "^2.3.8"
+    "jquery": "^3.6.0",
+    "katex": "^0.13.3",
+    "lunr": "^2.3.9"
   }
 }

data/lib/jazzy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'jazzy/config'
 require 'jazzy/doc_builder'
 

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,
@@ -192,7 +196,7 @@ module Jazzy
     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 +205,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,24 +217,26 @@ 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
 
-    SWIFT_BUILD_TOOLS = %w[spm xcodebuild].freeze
+    SWIFT_BUILD_TOOLS = %w[spm xcodebuild symbolgraph].freeze
 
     config_attr :swift_build_tool,
       command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
-      description: 'Control whether Jazzy uses Swift Package Manager or '\
-                   'xcodebuild to build the module to be documented.  By '\
-                   'default it uses xcodebuild if there is a .xcodeproj '\
-                   'file in the source directory.',
+      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.',
       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 ────────
@@ -253,14 +259,14 @@ module Jazzy
 
     config_attr :version,
       command_line: '--module-version VERSION',
-      description: 'Version string to use as part of the the default docs '\
-                   'title and inside the docset.',
+      description: 'Version string to use as part of the default docs '\
+        '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 +291,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 +322,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 +391,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 +400,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 +423,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 +444,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,10 +466,17 @@ 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'
 
-    # rubocop:enable Style/AlignParameter
+    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.',
+      default: false
+
+    # rubocop:enable Layout/ArgumentAlignment
 
     def initialize
       self.class.all_config_attrs.each do |attr|
@@ -450,7 +489,6 @@ module Jazzy
       Doc.template_path = theme_directory + 'templates'
     end
 
-    # rubocop:disable Metrics/MethodLength
     def self.parse!
       config = new
       config.parse_command_line
@@ -464,9 +502,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'
@@ -478,7 +523,7 @@ module Jazzy
         end
 
         opt.on('-v', '--version', 'Print version number') do
-          puts 'jazzy version: ' + Jazzy::VERSION
+          puts "jazzy version: #{Jazzy::VERSION}"
           exit
         end
 
@@ -497,6 +542,10 @@ module Jazzy
           exit
         end
       end.parse!
+
+      unless ARGV.empty?
+        warning "Leftover unused command-line text: #{ARGV}"
+      end
     end
 
     def parse_config_file
@@ -514,13 +563,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
 
@@ -530,6 +578,17 @@ 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
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
     def locate_config_file
       return config_file if config_file
 
@@ -543,15 +602,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
@@ -568,7 +622,7 @@ module Jazzy
 
         The config file can be in YAML or JSON format. Available options are:
 
-        _EOS_
+      _EOS_
         .gsub(/^ +/, '')
 
       print_option_help