jazzy 0.9.3 → 0.11.0

data/README.md

@@ -1,7 +1,5 @@
 ![jazzy](images/logo.jpg)
 
-![analytics](https://ga-beacon.appspot.com/UA-50247013-2/jazzy/README?pixel)
-
 [![Build Status](https://circleci.com/gh/realm/jazzy.svg?style=svg)](https://circleci.com/gh/realm/jazzy)
 
 *jazzy is a command-line utility that generates documentation for Swift or Objective-C*
@@ -10,7 +8,7 @@
 
 Both Swift and Objective-C projects are supported.
 
-*Objective-C support was recently added, so please report any issues you find.*
+*SwiftPM support was recently added, so please report any issues you find.*
 
 Instead of parsing your source files, `jazzy` hooks into [Clang][clang] and
 [SourceKit][sourcekit] to use the [AST][ast] representation of your code and
@@ -25,9 +23,8 @@ unacceptable behavior to [info@realm.io](mailto:info@realm.io).
 
 ## Requirements
 
-* A version of [Xcode][xcode] capable of building the project you wish to
-document. It must be installed in a location indexed by Spotlight for the
-`--swift-version` configuration option to succeed.
+* Development tools that can build the project you wish to document.  Jazzy supports
+  both [Xcode][xcode] and [Swift Package Manager][spm] projects.
 
 ## Installation
 
@@ -35,17 +32,17 @@ document. It must be installed in a location indexed by Spotlight for the
 [sudo] gem install jazzy
 ```
 
-The Xcode command-line developer tools must be installed to successfully build
-the gems that `jazzy` depends on: try `xcode-select --install` if you see build
-errors.
+See [Installation Problems](#installation-problems) for solutions to some
+common problems.
 
 ## Usage
 
 Run `jazzy` from your command line. Run `jazzy -h` for a list of additional options.
 
 If your Swift module is the first thing to build, and it builds fine when running
-`xcodebuild` without any arguments from the root of your project, then just running
-`jazzy` (without any arguments) from the root of your project should succeed too!
+`xcodebuild` or `swift build` without any arguments from the root of your project, then
+just running `jazzy` (without any arguments) from the root of your project should
+succeed too!
 
 You can set options for your project’s documentation in a configuration file,
 `.jazzy.yaml` by default. For a detailed explanation and an exhaustive list of
@@ -86,13 +83,22 @@ jazzy \
   --github_url https://github.com/realm/realm-cocoa \
   --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
   --module-version 0.96.2 \
-  --xcodebuild-arguments -scheme,RealmSwift \
+  --build-tool-arguments -scheme,RealmSwift \
   --module RealmSwift \
   --root-url https://realm.io/docs/swift/0.96.2/api/ \
   --output docs/swift_output \
   --theme docs/themes
 ```
 
+This is how docs are generated for a project that uses the Swift Package Manager:
+
+```shell
+jazzy \
+  --module DeckOfPlayingCards \
+  --swift-build-tool spm \
+  --build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5
+```
+
 ### Objective-C
 
 To generate documentation for Objective-C headers, you must pass the following
@@ -119,7 +125,7 @@ jazzy \
   --github_url https://github.com/realm/realm-cocoa \
   --github-file-prefix https://github.com/realm/realm-cocoa/tree/v2.2.0 \
   --module-version 2.2.0 \
-  --xcodebuild-arguments --objc,Realm/Realm.h,--,-x,objective-c,-isysroot,$(xcrun --show-sdk-path),-I,$(pwd) \
+  --build-tool-arguments --objc,Realm/Realm.h,--,-x,objective-c,-isysroot,$(xcrun --show-sdk-path),-I,$(pwd) \
   --module Realm \
   --root-url https://realm.io/docs/objc/2.2.0/api/ \
   --output docs/objc_output \
@@ -168,7 +174,7 @@ Any files found matching the file pattern will be parsed and included as a docum
 
 There are a few limitations:
 - File names must be unique from source files.
-- Readme should be specified separately using the `readme_path` option.
+- Readme should be specified separately using the `readme` option.
 
 ### Section description abstracts
 
@@ -222,14 +228,63 @@ Note that the `--include` option is applied before the `--exclude` option. For e
 Declarations with a documentation comment containing `:nodoc:` are excluded from the
 documentation.
 
+### Choosing the Swift language version
+
+Jazzy normally uses the Swift compiler from the Xcode currently configured by
+`xcode-select`.  Use the `--swift-version` flag to compile with a different
+Xcode.
+
+The value you pass to `--swift-version` must be the Swift language version given
+by `swift --version` in the Xcode you want to use.
+
+For example to use Xcode 9.4:
+```shell
+jazzy --swift-version 4.1.2
+```
+
 ## Troubleshooting
 
-#### Swift
+### Swift
 
 **Only extensions are listed in the documentation?**
 
 Check the `--min-acl` setting -- see [above](#controlling-what-is-documented).
 
+**Unable to find an Xcode with swift version X**
+
+1. The value passed with `--swift-version` must exactly match the version
+   number from `swiftc --version`.  For example Xcode 10.1 needs
+   `--swift-version 4.2.1`.  See [the flag documentation](#choosing-the-swift-language-version).
+2. The Xcode you want to use must be in the Spotlight index.  You can check
+   this using `mdfind 'kMDItemCFBundleIdentifier == com.apple.dt.Xcode'`.
+   Some users have reported this issue being fixed by a reboot; `mdutil -E`
+   may also help.  If none of these work then you can set the `DEVELOPER_DIR`
+   environment variable to point to the Xcode you want before running Jazzy
+   without the `--swift-version` flag.
+
+### Installation Problems
+
+**Can't find header files / clang**
+
+Some of the Ruby gems that Jazzy depends on have native C extensions.  This
+means you need the Xcode command-line developer tools installed to build
+them: run `xcode-select --install` to install the tools.
+
+**/Applications/Xcode: No such file or directory**
+
+The path of your active Xcode installation must not contain spaces.  So
+`/Applications/Xcode.app/` is fine, `/Applications/Xcode-10.2.app/` is fine,
+but `/Applications/Xcode 10.2.app/` is not.  This restriction applies only
+when *installing* Jazzy, not running it.
+
+### MacOS Before 10.14.4
+
+Starting with Jazzy 0.10.0, if you see an error similar to `dyld: Symbol not found: _$s11SubSequenceSlTl` then you need to install the [Swift 5 Runtime Support for Command Line Tools](https://support.apple.com/kb/DL1998).
+
+Alternatively, you can:
+* Update to macOS 10.14.4 or later; or
+* Install Xcode 10.2 or later at `/Applications/Xcode.app`.
+
 ## Development
 
 Please review jazzy's [contributing guidelines](https://github.com/realm/jazzy/blob/master/CONTRIBUTING.md) when submitting pull requests.
@@ -280,3 +335,4 @@ read [our blog](https://realm.io/news) or say hi on twitter
 [SourceKitten]: https://github.com/jpsim/SourceKitten "SourceKitten"
 [bundler]: https://rubygems.org/gems/bundler
 [mustache]: https://mustache.github.io "Mustache"
+[spm]: https://swift.org/package-manager/ "Swift Package Manager"

data/Rakefile

@@ -75,13 +75,14 @@ begin
 
     # Remove files not used for the comparison
     # To keep the git diff clean
-    files_glob = 'spec/integration_specs/*/after/{*,.*}'
+    specs_root = 'spec/integration_specs/*/after'
+    files_glob = "#{specs_root}/{*,.*}"
     files_to_delete = FileList[files_glob]
       .exclude('**/.', '**/..')
-      .exclude('spec/integration_specs/*/after/*docs',
-               'spec/integration_specs/*/after/execution_output.txt')
-      .include('**/*.dsidx')
-      .include('**/*.tgz')
+      .exclude("#{specs_root}/*docs",
+               "#{specs_root}/execution_output.txt")
+      .include("#{specs_root}/**/*.dsidx")
+      .include("#{specs_root}/**/*.tgz")
     files_to_delete.each do |file_to_delete|
       sh "rm -rf '#{file_to_delete}'"
     end
@@ -103,7 +104,7 @@ begin
   task :sourcekitten do
     sk_dir = 'SourceKitten'
     Dir.chdir(sk_dir) do
-      `swift build -c release -Xswiftc -static-stdlib`
+      `swift build -c release`
     end
     FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
   end

data/jazzy.gemspec

@@ -17,12 +17,12 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split($/)
   spec.executables   << 'jazzy'
 
-  spec.add_runtime_dependency 'cocoapods', '~> 1.0'
-  spec.add_runtime_dependency 'mustache', '~> 0.99'
+  spec.add_runtime_dependency 'cocoapods', '~> 1.5'
+  spec.add_runtime_dependency 'mustache', '~> 1.1'
   spec.add_runtime_dependency 'open4'
-  spec.add_runtime_dependency 'redcarpet', '~> 3.2'
+  spec.add_runtime_dependency 'redcarpet', '~> 3.4'
   spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
-  spec.add_runtime_dependency 'sass', '~> 3.4'
+  spec.add_runtime_dependency 'sassc', '~> 2.1'
   spec.add_runtime_dependency 'sqlite3', '~> 1.3'
   spec.add_runtime_dependency 'xcinvoke', '~> 0.3.0'
 

data/lib/jazzy/config.rb

@@ -2,7 +2,6 @@ require 'optparse'
 require 'pathname'
 require 'uri'
 
-require 'jazzy/doc'
 require 'jazzy/podspec_documenter'
 require 'jazzy/source_declaration/access_control_level'
 
@@ -80,16 +79,29 @@ module Jazzy
       @all_config_attrs << Attribute.new(name, **opts)
     end
 
+    def self.alias_config_attr(name, forward, **opts)
+      alias_method name.to_s, forward.to_s
+      alias_method "#{name}=", "#{forward}="
+      alias_method "#{name}_configured", "#{forward}_configured"
+      alias_method "#{name}_configured=", "#{forward}_configured="
+      @all_config_attrs << Attribute.new(name, **opts)
+    end
+
     class << self
       attr_reader :all_config_attrs
     end
 
     attr_accessor :base_path
 
-    def expand_path(path)
+    def expand_glob_path(path)
       Pathname(path).expand_path(base_path) # nil means Pathname.pwd
     end
 
+    def expand_path(path)
+      abs_path = expand_glob_path(path)
+      Pathname(Dir[abs_path][0] || abs_path) # Use existing filesystem spelling
+    end
+
     # ──────── Build ────────
 
     # rubocop:disable Layout/AlignParameters
@@ -142,11 +154,16 @@ module Jazzy
                     'Default: .jazzy.yaml in source directory or ancestor'],
       parse: ->(cf) { expand_path(cf) }
 
-    config_attr :xcodebuild_arguments,
-      command_line: ['-x', '--xcodebuild-arguments arg1,arg2,…argN', Array],
-      description: 'Arguments to forward to xcodebuild',
+    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.',
       default: []
 
+    alias_config_attr :xcodebuild_arguments, :build_tool_arguments,
+      command_line: ['-x', '--xcodebuild-arguments arg1,arg2,…argN', Array],
+      description: 'Back-compatibility alias for build_tool_arguments.'
+
     config_attr :sourcekitten_sourcefile,
       command_line: ['-s', '--sourcekitten-sourcefile FILEPATH'],
       description: 'File generated from sourcekitten output to parse',
@@ -164,7 +181,7 @@ module Jazzy
                    'Supports wildcards.',
       default: [],
       parse: ->(files) do
-        Array(files).map { |f| expand_path(f).to_s }
+        Array(files).map { |f| expand_glob_path(f).to_s }
       end
 
     config_attr :included_files,
@@ -173,7 +190,7 @@ module Jazzy
                    'Supports wildcards.',
       default: [],
       parse: ->(files) do
-        Array(files).map { |f| expand_path(f).to_s }
+        Array(files).map { |f| expand_glob_path(f).to_s }
       end
 
     config_attr :swift_version,
@@ -188,6 +205,20 @@ module Jazzy
         end
       end
 
+    SWIFT_BUILD_TOOLS = %w[spm xcodebuild].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.',
+      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(', ')}"
+      end
+
     # ──────── Metadata ────────
 
     config_attr :author_name,
@@ -208,9 +239,16 @@ module Jazzy
 
     config_attr :version,
       command_line: '--module-version VERSION',
-      description: 'module version. will be used when generating docset',
+      description: 'Version string to use as part of the 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: ''
+
     config_attr :copyright,
       command_line: '--copyright COPYRIGHT_MARKDOWN',
       description: 'copyright markdown rendered at the bottom of the docs pages'

data/lib/jazzy/doc.rb

@@ -8,10 +8,11 @@ require 'jazzy/jazzy_markdown'
 
 module Jazzy
   class Doc < Mustache
+    include Config::Mixin
+
     self.template_name = 'doc'
 
     def copyright
-      config = Config.instance
       copyright = config.copyright || (
         # Fake date is used to keep integration tests consistent
         date = ENV['JAZZY_FAKE_DATE'] || DateTime.now.strftime('%Y-%m-%d')
@@ -28,7 +29,7 @@ module Jazzy
     end
 
     def objc_first?
-      Config.instance.objc_mode && Config.instance.hide_declarations != 'objc'
+      config.objc_mode && config.hide_declarations != 'objc'
     end
 
     def language
@@ -38,5 +39,21 @@ module Jazzy
     def language_stub
       objc_first? ? 'objc' : 'swift'
     end
+
+    def module_version
+      config.version_configured ? config.version : nil
+    end
+
+    def docs_title
+      if config.title_configured
+        config.title
+      elsif config.version_configured
+        # Fake version for integration tests
+        version = ENV['JAZZY_FAKE_MODULE_VERSION'] || config.version
+        "#{config.module_name} #{version} Docs"
+      else
+        "#{config.module_name} Docs"
+      end
+    end
   end
 end

data/lib/jazzy/doc_builder.rb

@@ -1,7 +1,7 @@
 require 'fileutils'
 require 'mustache'
 require 'pathname'
-require 'sass'
+require 'sassc'
 
 require 'jazzy/config'
 require 'jazzy/doc'
@@ -10,7 +10,6 @@ require 'jazzy/documentation_generator'
 require 'jazzy/search_builder'
 require 'jazzy/jazzy_markdown'
 require 'jazzy/podspec_documenter'
-require 'jazzy/readme_generator'
 require 'jazzy/source_declaration'
 require 'jazzy/source_document'
 require 'jazzy/source_module'
@@ -56,21 +55,13 @@ module Jazzy
     def self.build(options)
       if options.sourcekitten_sourcefile
         stdout = options.sourcekitten_sourcefile.read
+      elsif options.podspec_configured
+        pod_documenter = PodspecDocumenter.new(options.podspec)
+        stdout = pod_documenter.sourcekitten_output(options)
       else
-        if options.podspec_configured
-          pod_documenter = PodspecDocumenter.new(options.podspec)
-          stdout = pod_documenter.sourcekitten_output(options)
-        else
-          stdout = Dir.chdir(options.source_directory) do
-            arguments = SourceKitten.arguments_from_options(options)
-            SourceKitten.run_sourcekitten(arguments)
-          end
-        end
-        unless $?.success?
-          warn 'Please pass in xcodebuild arguments using -x'
-          warn 'If build arguments are correct, please file an issue on ' \
-            'https://github.com/realm/jazzy/issues'
-          exit $?.exitstatus || 1
+        stdout = Dir.chdir(options.source_directory) do
+          arguments = SourceKitten.arguments_from_options(options)
+          SourceKitten.run_sourcekitten(arguments)
         end
       end
 
@@ -95,11 +86,10 @@ module Jazzy
 
     def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
-        next unless doc.render?
-        # Assuming URL is relative to documentation root:
-        path = output_dir + (doc.url || "#{doc.name}.html")
+        next unless doc.render_as_page?
+        # Filepath is relative to documentation root:
+        path = output_dir + doc.filepath
         block.call(doc, path)
-        next if doc.name == 'index'
         each_doc(
           output_dir,
           doc.children,
@@ -199,8 +189,7 @@ module Jazzy
       assets_directory = Config.instance.theme_directory + 'assets'
       FileUtils.cp_r(assets_directory.children, destination)
       Pathname.glob(destination + 'css/**/*.scss').each do |scss|
-        contents = scss.read
-        css = Sass::Engine.new(contents, syntax: :scss).render
+        css = SassC::Engine.new(scss.read).render
         css_filename = scss.sub(/\.scss$/, '')
         css_filename.open('w') { |f| f.write(css) }
         FileUtils.rm scss
@@ -332,6 +321,7 @@ module Jazzy
     # Build mustache item for a top-level doc
     # @param [Hash] item Parsed doc child item
     # @param [Config] options Build options
+    # rubocop:disable Metrics/MethodLength
     def self.render_item(item, source_module)
       # Combine abstract and discussion into abstract
       abstract = (item.abstract || '') + (item.discussion || '')
@@ -347,11 +337,16 @@ module Jazzy
         from_protocol_extension:    item.from_protocol_extension,
         return:                     item.return,
         parameters:                 (item.parameters if item.parameters.any?),
-        url:                        (item.url if item.children.any?),
+        url:                        (item.url if item.render_as_page?),
         start_line:                 item.start_line,
         end_line:                   item.end_line,
+        direct_link:                item.omit_content_from_parent?,
+        deprecation_message:        item.deprecation_message,
+        unavailable_message:        item.unavailable_message,
+        usage_discouraged:          item.usage_discouraged?,
       }
     end
+    # rubocop:enable Metrics/MethodLength
 
     def self.make_task(mark, uid, items)
       {
@@ -391,7 +386,7 @@ module Jazzy
     # @param [Array] doc_structure doc structure comprised of section names and
     #        child names and URLs. @see doc_structure_for_docs
     def self.document(source_module, doc_model, path_to_root)
-      if doc_model.type.kind == 'document.markdown'
+      if doc_model.type.markdown?
         return document_markdown(source_module, doc_model, path_to_root)
       end
 
@@ -418,6 +413,9 @@ module Jazzy
       doc[:github_url] = source_module.github_url
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
+      doc[:deprecation_message] = doc_model.deprecation_message
+      doc[:unavailable_message] = doc_model.unavailable_message
+      doc[:usage_discouraged] = doc_model.usage_discouraged?
       doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
     end
     # rubocop:enable Metrics/MethodLength