jazzy 0.13.7 → 0.14.0

data/README.md

@@ -13,7 +13,7 @@ Instead of parsing your source files, `jazzy` hooks into [Clang][clang] and
 its comments for more accurate results. The output matches the look and feel
 of Apple’s official reference documentation, post WWDC 2014.
 
-Jazzy can also generate documentation from compiled swift modules [using their
+Jazzy can also generate documentation from compiled Swift modules [using their
 symbol graph](#docs-from-swiftmodules-or-frameworks) instead of source code.
 
 ![Screenshot](images/screenshot.jpg)
@@ -60,8 +60,11 @@ all available options, run `jazzy --help config`.
 ### Supported documentation keywords
 
 Swift documentation is written in markdown and supports a number of special keywords.
-For a complete list and examples, see Erica Sadun's post on [*Swift header documentation in Xcode 7*](https://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/),
-her [book on Swift Documentation Markup](https://itunes.apple.com/us/book/swift-documentation-markup/id1049010423), and the [Xcode Markup Formatting Reference](https://developer.apple.com/library/content/documentation/Xcode/Reference/xcode_markup_formatting_ref/).
+Here are some resources with tutorials and examples, starting with the most modern:
+* Apple's [Writing Symbol Documentation in Your Source Files](https://developer.apple.com/documentation/xcode/writing-symbol-documentation-in-your-source-files) article.
+* Apple's [Formatting Your Documentation Content](https://developer.apple.com/documentation/xcode/formatting-your-documentation-content) article.
+* Apple's [Xcode Markup Formatting Reference](https://developer.apple.com/library/content/documentation/Xcode/Reference/xcode_markup_formatting_ref/).
+* Erica Sadun's [Swift header documentation in Xcode 7](https://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/) post and her [book on Swift Documentation Markup](https://itunes.apple.com/us/book/swift-documentation-markup/id1049010423).
 
 For Objective-C documentation the same keywords are supported, but note that the format
 is slightly different. In Swift you would write `- returns:`, but in Objective-C you write `@return`. See Apple's [*HeaderDoc User Guide*](https://developer.apple.com/legacy/library/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html) for more details. **Note: `jazzy` currently does not support _all_ Objective-C keywords listed in this document, only @param, @return, @warning, @see, and @note.**
@@ -76,6 +79,12 @@ backticks generates a link, for example:
 * \`[MyClass method1]\` - a link to an Objective-C method.
 * \`-[MyClass method2:param1]\` - a link to another Objective-C method.
 
+Jazzy understands Apple's DocC-style links too, for example:
+* \`\`MyClass/method(param1:)\`\` - a link to the documentation for that method
+  that appears as just `method(param1:)` in the rendered page.
+* \`\`\<doc:method(_:)-e873\>\`\` - a link to a specific overload of `method(_:)`.
+  Jazzy can't tell which overload you intend and links to the first one.
+
 ### Math
 
 Jazzy can render math equations written in LaTeX embedded in your markdown:
@@ -108,8 +117,9 @@ jazzy \
   --clean \
   --author Realm \
   --author_url https://realm.io \
-  --github_url https://github.com/realm/realm-cocoa \
-  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
+  --source-host github \
+  --source-host-url https://github.com/realm/realm-cocoa \
+  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v0.96.2 \
   --module-version 0.96.2 \
   --build-tool-arguments -scheme,RealmSwift \
   --module RealmSwift \
@@ -150,8 +160,9 @@ jazzy \
   --clean \
   --author Realm \
   --author_url https://realm.io \
-  --github_url https://github.com/realm/realm-cocoa \
-  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v2.2.0 \
+  --source-host github \
+  --source-host-url https://github.com/realm/realm-cocoa \
+  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v2.2.0 \
   --module-version 2.2.0 \
   --build-tool-arguments --objc,Realm/Realm.h,--,-x,objective-c,-isysroot,$(xcrun --show-sdk-path),-I,$(pwd) \
   --module Realm \
@@ -167,8 +178,9 @@ jazzy \
   --objc \
   --author AFNetworking \
   --author_url http://afnetworking.com \
-  --github_url https://github.com/AFNetworking/AFNetworking \
-  --github-file-prefix https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
+  --source-host github \
+  --source-host-url https://github.com/AFNetworking/AFNetworking \
+  --source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
   --module-version 2.6.2 \
   --umbrella-header AFNetworking/AFNetworking.h \
   --framework-root . \
@@ -227,7 +239,7 @@ Some examples:
    ```shell
    jazzy --module Combine --swift-build-tool symbolgraph
          --sdk iphoneos
-         --build-tool-arguments --target,arm64-apple-ios14.1
+         --build-tool-arguments -target,arm64-apple-ios14.1
    ```
    The `target` is the LLVM target triple and needs to match the SDK.  The
    default here is the target of the host system that Jazzy is running on,
@@ -249,7 +261,7 @@ Some examples:
    a `.swiftmodule`.  Again the `--source-directory` is searched by default
    if `-F` is not passed in.
 
-See `swift symbolgraph-extract --help` for all the things you can pass via
+See `swift symbolgraph-extract -help` for all the things you can pass via
 `--build-tool-arguments`: if your module has dependencies then you may need
 to add various search path options to let Swift load it.
 

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,20 +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'
+      '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 +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/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,8 +217,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 +229,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 +260,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 +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,17 +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'
 
     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
 
-    # rubocop:enable Style/AlignParameter
+    # rubocop:enable Layout/ArgumentAlignment
 
     def initialize
       self.class.all_config_attrs.each do |attr|
@@ -457,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
@@ -471,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'
@@ -485,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
 
@@ -504,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
@@ -521,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
 
@@ -537,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
 
@@ -550,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
@@ -575,7 +622,7 @@ module Jazzy
 
         The config file can be in YAML or JSON format. Available options are:
 
-        _EOS_
+      _EOS_
         .gsub(/^ +/, '')
 
       print_option_help