jazzy 0.9.6 → 0.12.0

data/README.md

@@ -8,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
@@ -23,9 +23,11 @@ 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.
+You need development tools to build the project you wish to document.  Jazzy supports
+both [Xcode][xcode] and [Swift Package Manager][spm] projects.
+
+Jazzy expects to be running on __macOS__.  See [below](#linux) for tips to run Jazzy
+on Linux.
 
 ## Installation
 
@@ -41,8 +43,9 @@ common problems.
 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
@@ -83,13 +86,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
@@ -116,7 +128,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 \
@@ -138,6 +150,33 @@ jazzy \
   --module AFNetworking
 ```
 
+### Mixed Objective-C / Swift
+
+*This feature is new and has some rough edges.*
+
+To generate documentation for a mixed Swift and Objective-C project you must first
+generate two [SourceKitten][sourcekitten] files: one for Swift and one for Objective-C.
+
+Then pass these files to Jazzy together using `--sourcekitten-sourcefile`.
+
+#### Example
+
+This is how docs are generated from an Xcode project for a module containing both
+Swift and Objective-C files:
+
+```shell
+# Generate Swift SourceKitten output
+sourcekitten doc -- -workspace MyProject.xcworkspace -scheme MyScheme > swiftDoc.json
+
+# Generate Objective-C SourceKitten output
+sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
+      -- -x objective-c  -isysroot $(xcrun --show-sdk-path --sdk iphonesimulator) \
+      -I $(pwd) -fmodules > objcDoc.json
+
+# Feed both outputs to Jazzy as a comma-separated list
+jazzy --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
+```
+
 ### Themes
 
 Three themes are provided with jazzy: `apple` (default), `fullwidth` and `jony`.
@@ -233,9 +272,27 @@ For example to use Xcode 9.4:
 jazzy --swift-version 4.1.2
 ```
 
+## Linux
+
+Jazzy uses [SourceKitten][sourcekitten] to communicate with the Swift build
+environment and compiler.  The `sourcekitten` binary included in the Jazzy gem
+is built for macOS and so does not run on other operating systems.
+
+To use Jazzy on Linux you first need to install and build `sourcekitten`
+following instructions from [SourceKitten's GitHub repository][sourcekitten].
+
+Then to generate documentation for a SwiftPM project, instead of running just
+`jazzy` do:
+```shell
+sourcekitten doc --spm > doc.json
+jazzy --sourcekitten-sourcefile doc.json
+```
+
+We hope to improve this process in the future.
+
 ## Troubleshooting
 
-#### Swift
+### Swift
 
 **Only extensions are listed in the documentation?**
 
@@ -253,7 +310,7 @@ Check the `--min-acl` setting -- see [above](#controlling-what-is-documented).
    environment variable to point to the Xcode you want before running Jazzy
    without the `--swift-version` flag.
 
-#### Installation Problems
+### Installation Problems
 
 **Can't find header files / clang**
 
@@ -268,6 +325,14 @@ The path of your active Xcode installation must not contain spaces.  So
 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.
@@ -293,7 +358,7 @@ Instructions to build SourceKitten from source can be found at
 - Leverage modern HTML templating ([Mustache][mustache])
 - Leverage the power and accuracy of the [Clang AST][ast] and [SourceKit][sourcekit]
 - Support for Dash docsets
-- Support Swift and Objective-C (*mixed projects are a work in progress*)
+- Support Swift and Objective-C
 
 ## License
 
@@ -318,3 +383,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

@@ -104,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,13 +17,13 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split($/)
   spec.executables   << 'jazzy'
 
-  spec.add_runtime_dependency 'cocoapods', '~> 1.5.3'
-  spec.add_runtime_dependency 'mustache', '~> 1.1.0'
+  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.4.0'
+  spec.add_runtime_dependency 'redcarpet', '~> 3.4'
   spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
-  spec.add_runtime_dependency 'sass', '~> 3.6.0'
-  spec.add_runtime_dependency 'sqlite3', '~> 1.3.13'
+  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'

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,6 +79,14 @@ 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
@@ -95,6 +102,14 @@ module Jazzy
       Pathname(Dir[abs_path][0] || abs_path) # Use existing filesystem spelling
     end
 
+    def hide_swift?
+      hide_declarations == 'swift'
+    end
+
+    def hide_objc?
+      hide_declarations == 'objc'
+    end
+
     # ──────── Build ────────
 
     # rubocop:disable Layout/AlignParameters
@@ -136,9 +151,9 @@ module Jazzy
       command_line: '--hide-declarations [objc|swift] ',
       description: 'Hide declarations in the specified language. Given that ' \
                    'generating Swift docs only generates Swift declarations, ' \
-                   'this is only really useful to display just the Swift ' \
-                   'declarations & names when generating docs for an ' \
-                   'Objective-C framework.',
+                   'this is useful for hiding a specific interface for ' \
+                   'either Objective-C or mixed Objective-C and Swift ' \
+                   'projects.',
       default: ''
 
     config_attr :config_file,
@@ -147,15 +162,21 @@ 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',
-      parse: ->(s) { expand_path(s) }
+      command_line: ['-s', '--sourcekitten-sourcefile filepath1,…filepathN',
+                     Array],
+      description: 'File(s) generated from sourcekitten output to parse',
+      parse: ->(paths) { paths.map { |path| expand_path(path) } }
 
     config_attr :source_directory,
       command_line: '--source-directory DIRPATH',
@@ -193,6 +214,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,
@@ -213,9 +248,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,15 +29,27 @@ module Jazzy
     end
 
     def objc_first?
-      Config.instance.objc_mode && Config.instance.hide_declarations != 'objc'
-    end
-
-    def language
-      objc_first? ? 'Objective-C' : 'Swift'
+      config.objc_mode && config.hide_declarations != 'objc'
     end
 
     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'
@@ -53,23 +53,16 @@ module Jazzy
     # @param [Config] options
     # @return [SourceModule] the documented source module
     def self.build(options)
-      if options.sourcekitten_sourcefile
-        stdout = options.sourcekitten_sourcefile.read
+      if options.sourcekitten_sourcefile_configured
+        stdout = '[' + options.sourcekitten_sourcefile.map(&:read)
+                              .join(',') + ']'
+      elsif options.podspec_configured
+        pod_documenter = PodspecDocumenter.new(options.podspec)
+        stdout = pod_documenter.sourcekitten_output(options)
       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,10 +88,9 @@ module Jazzy
     def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
         next unless doc.render_as_page?
-        # Assuming URL is relative to documentation root:
-        path = output_dir + (doc.url || "#{doc.name}.html")
+        # 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,
@@ -198,8 +190,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
@@ -339,6 +330,7 @@ module Jazzy
         name:                       item.name,
         abstract:                   abstract,
         declaration:                item.display_declaration,
+        language:                   item.display_language,
         other_language_declaration: item.display_other_language_declaration,
         usr:                        item.usr,
         dash_type:                  item.type.dash_type,

data/lib/jazzy/docset_builder.rb

@@ -78,7 +78,7 @@ module Jazzy
             'searchIndex (name, type, path);')
           source_module.all_declarations.select(&:type).each do |doc|
             db.execute('INSERT OR IGNORE INTO searchIndex(name, type, path) ' \
-              'VALUES (?, ?, ?);', [doc.name, doc.type.dash_type, doc.url])
+              'VALUES (?, ?, ?);', [doc.name, doc.type.dash_type, doc.filepath])
           end
         end
       end

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.9.6'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.12.0'.freeze unless defined? Jazzy::VERSION
 end

data/lib/jazzy/highlighter.rb

@@ -3,6 +3,9 @@ require 'rouge'
 module Jazzy
   # This module helps highlight code
   module Highlighter
+    SWIFT = 'swift'.freeze
+    OBJC = 'objective_c'.freeze
+
     class Formatter < Rouge::Formatters::HTML
       def initialize(language)
         @language = language
@@ -16,16 +19,15 @@ module Jazzy
       end
     end
 
-    # What Rouge calls the language
-    def self.default_language
-      if Config.instance.objc_mode
-        'objective_c'
-      else
-        'swift'
-      end
+    def self.highlight_swift(source)
+      highlight(source, SWIFT)
+    end
+
+    def self.highlight_objc(source)
+      highlight(source, OBJC)
     end
 
-    def self.highlight(source, language = default_language)
+    def self.highlight(source, language)
       source && Rouge.highlight(source, language, Formatter.new(language))
     end
   end