jazzy 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc3616cb1da2da7c201cea6c6bc81659ee5a816da770bc8cc5c087b75e227a19
-  data.tar.gz: 9a459463afd8a9b12881175acb5c638d1c27d4f86f6a78898d4d04fd77a2912f
+  metadata.gz: 6439cb8dc035d69bb0243f06e3b7140b079dd6892840b49e015be636efa7ff64
+  data.tar.gz: fc97247251923d0f385637721405435e2a3211110c14369876767e2572a25175
 SHA512:
-  metadata.gz: d7e283f41d40a59988031091c64b1be2fc8a78334a3e544d4e00cfe2cb08beebffd2c2148e2e82cd8db63125c88a7ea8d1262e16c8fca1440ee8ef5f64cfbc89
-  data.tar.gz: fa1111eda7b0f9f4d06ee49ddd1f114d0625970f77f3ef6515ddac933ce4551eed8852db56e89b95fa80f82e28b75508ecaf90e303df994659a169ae732cf9c7
+  metadata.gz: 4049263b20f10ed92f23f23971df8d2fd57a58d95f0312fd34c5c36f1be170b6889ea82a31f3a972505025d69e4ce3f0b55343b17794ccff06bde3a46d87db3c
+  data.tar.gz: 10ac755d262c1a19c451b8dce5969924bd95f1f5601ae5f76c2fb748ac6f74d92b3bc6240334a185da3a6a8987a29ea3cc27c138b666d6e95ed0ed9ea930d833

data/CHANGELOG.md

@@ -1,3 +1,46 @@
+## 0.11.0
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Sass support now provided by `libsass` via `sassc` instead of the
+  deprecated Ruby Sass gem.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Update bundled jQuery to 3.4.1 (all themes).  
+  [Paul Idstein](https://github.com/idstein)
+
+* Support Xcode 11 Swift projects that pass a response file to the Swift
+  compiler.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1087](https://github.com/realm/jazzy/issues/1087)
+
+* Generate Swift docs from a Swift Package Manager package without
+  requiring an Xcode project file.  Add `--swift-build-tool` to choose
+  the build method if both `.xcodeproj` and `Package.swift` files are
+  present.  Add `--build-tool-flags` as a preferred alias for
+  `--xcodebuild-flags`.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#487](https://github.com/realm/jazzy/issues/487)
+
+##### Bug Fixes
+
+* Preserve non-latin characters in guide filenames and heading IDs.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1091](https://github.com/realm/jazzy/issues/1091)
+
+* Generate correct html for custom categories containing special
+  characters.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#945](https://github.com/realm/jazzy/issues/945)
+
+* Fix crash on files with misplaced documentation comments.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1083](https://github.com/realm/jazzy/issues/1083)
+
 ## 0.10.0
 
 ##### Breaking

data/Gemfile.lock

@@ -1,20 +1,20 @@
 PATH
   remote: .
   specs:
-    jazzy (0.10.0)
+    jazzy (0.11.0)
       cocoapods (~> 1.5)
       mustache (~> 1.1)
       open4
       redcarpet (~> 3.4)
       rouge (>= 2.0.6, < 4.0)
-      sass (~> 3.6)
+      sassc (~> 2.1)
       sqlite3 (~> 1.3)
       xcinvoke (~> 0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.0)
+    CFPropertyList (3.0.1)
     activesupport (4.2.11.1)
       i18n (~> 0.7)
       minitest (~> 5.1)
@@ -33,10 +33,10 @@ GEM
     clintegracon (0.7.0)
       colored (~> 1.2)
       diffy
-    cocoapods (1.7.2)
+    cocoapods (1.7.5)
       activesupport (>= 4.0.2, < 5)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.7.2)
+      cocoapods-core (= 1.7.5)
       cocoapods-deintegrate (>= 1.0.3, < 2.0)
       cocoapods-downloader (>= 1.2.2, < 2.0)
       cocoapods-plugins (>= 1.0.0, < 2.0)
@@ -52,7 +52,7 @@ GEM
       nap (~> 1.0)
       ruby-macho (~> 1.4)
       xcodeproj (>= 1.10.0, < 2.0)
-    cocoapods-core (1.7.2)
+    cocoapods-core (1.7.5)
       activesupport (>= 4.0.2, < 6)
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
@@ -62,7 +62,7 @@ GEM
       nap
     cocoapods-search (1.0.0)
     cocoapods-stats (1.1.0)
-    cocoapods-trunk (1.3.1)
+    cocoapods-trunk (1.4.0)
       nap (>= 0.8, < 2.0)
       netrc (~> 0.11)
     cocoapods-try (1.1.0)
@@ -130,11 +130,8 @@ GEM
     rainbow (2.2.2)
       rake
     rake (10.5.0)
-    rb-fsevent (0.10.3)
-    rb-inotify (0.10.0)
-      ffi (~> 1.0)
-    redcarpet (3.4.0)
-    rouge (3.4.1)
+    redcarpet (3.5.0)
+    rouge (3.10.0)
     rubocop (0.49.0)
       parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)
@@ -145,11 +142,8 @@ GEM
     ruby-macho (1.4.0)
     ruby-progressbar (1.10.1)
     safe_yaml (1.0.5)
-    sass (3.7.4)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
+    sassc (2.2.0)
+      ffi (~> 1.9)
     sawyer (0.8.2)
       addressable (>= 2.3.5)
       faraday (> 0.8, < 2.0)
@@ -166,7 +160,7 @@ GEM
       hashdiff (>= 0.4.0, < 2.0.0)
     xcinvoke (0.3.0)
       liferaft (~> 0.0.6)
-    xcodeproj (1.10.0)
+    xcodeproj (1.12.0)
       CFPropertyList (>= 2.3.3, < 4.0)
       atomos (~> 0.1.3)
       claide (>= 1.0.2, < 2.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,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
 
@@ -41,8 +40,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 +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
@@ -116,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 \
@@ -326,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/jazzy.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'open4'
   spec.add_runtime_dependency 'redcarpet', '~> 3.4'
   spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
-  spec.add_runtime_dependency 'sass', '~> 3.6'
+  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

@@ -79,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
@@ -146,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',
@@ -192,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,

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'
@@ -55,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,10 +87,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 +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

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.10.0'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.11.0'.freeze unless defined? Jazzy::VERSION
 end

data/lib/jazzy/jazzy_markdown.rb

@@ -11,7 +11,7 @@ module Jazzy
       attr_accessor :default_language
 
       def header(text, header_level)
-        text_slug = text.gsub(/[^\w]+/, '-')
+        text_slug = text.gsub(/[^[[:word:]]]+/, '-')
                         .downcase
                         .sub(/^-/, '')
                         .sub(/-$/, '')

data/lib/jazzy/source_declaration.rb

@@ -111,6 +111,10 @@ module Jazzy
       unavailable || deprecated
     end
 
+    def filepath
+      CGI.unescape(url)
+    end
+
     def alternative_abstract
       if file = alternative_abstract_file
         Pathname(file).read

data/lib/jazzy/source_document.rb

@@ -20,6 +20,7 @@ module Jazzy
     def self.make_index(readme_path)
       SourceDocument.new.tap do |sd|
         sd.name = 'index'
+        sd.url = sd.name + '.html'
         sd.readme_path = readme_path
       end
     end
@@ -36,8 +37,8 @@ module Jazzy
       Config.instance
     end
 
-    def url
-      name.downcase.strip.tr(' ', '-').gsub(/[^\w-]/, '') + '.html'
+    def url_name
+      name.downcase.strip.tr(' ', '-').gsub(/[^[[:word:]]-]/, '')
     end
 
     def content(source_module)

data/lib/jazzy/sourcekitten.rb

@@ -126,12 +126,11 @@ module Jazzy
     # @return [Hash] input docs with URLs
     def self.make_doc_urls(docs)
       docs.each do |doc|
-        if !doc.parent_in_docs || doc.children.count > 0
-          # Create HTML page for this doc if it has children or is root-level
+        if doc.render_as_page?
           doc.url = (
             subdir_for_doc(doc) +
             [sanitize_filename(doc) + '.html']
-          ).join('/')
+          ).map { |path| ERB::Util.url_encode(path) }.join('/')
           doc.children = make_doc_urls(doc.children)
         else
           # Don't create HTML page for this doc if it doesn't have children
@@ -140,8 +139,8 @@ module Jazzy
             warn 'A compile error prevented ' + doc.fully_qualified_name +
                  ' from receiving a unique USR. Documentation may be ' \
                  'incomplete. Please check for compile errors by running ' \
-                 '`xcodebuild ' \
-                 "#{Config.instance.xcodebuild_arguments.shelljoin}`."
+                 '`xcodebuild` or `swift build` with arguments ' \
+                 "`#{Config.instance.build_tool_arguments.shelljoin}`."
           end
           id = doc.usr
           unless id
@@ -159,17 +158,17 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
 
-    # Determine the subdirectory in which a doc should be placed
+    # Determine the subdirectory in which a doc should be placed.
+    # Guides in the root for back-compatibility.
+    # Declarations under outer namespace type (Structures, Classes, etc.)
     def self.subdir_for_doc(doc)
-      # We always want to create top-level subdirs according to type (Struct,
-      # Class, etc).
+      return [] if doc.type.markdown?
       top_level_decl = doc.namespace_path.first
-      if top_level_decl && top_level_decl.type && top_level_decl.type.name
-        # File program elements under top ancestor’s type (Struct, Class, etc.)
+      if top_level_decl.type.name
         [top_level_decl.type.plural_url_name] +
           doc.namespace_ancestors.map(&:name)
       else
-        # Categories live in their own directory
+        # Category - in the root
         []
       end
     end
@@ -183,22 +182,31 @@ module Jazzy
       end.select { |x| x }.flatten(1)
     end
 
+    def self.use_spm?(options)
+      options.swift_build_tool == :spm ||
+        (!options.swift_build_tool_configured &&
+         Dir['*.xcodeproj'].empty?)
+    end
+
     # Builds SourceKitten arguments based on Jazzy options
     def self.arguments_from_options(options)
       arguments = ['doc']
-      arguments += if options.objc_mode
-                     objc_arguments_from_options(options)
-                   elsif !options.module_name.empty?
-                     ['--module-name', options.module_name, '--']
-                   else
-                     ['--']
-                   end
-      arguments + options.xcodebuild_arguments
+      if options.objc_mode
+        arguments += objc_arguments_from_options(options)
+      else
+        arguments += ['--spm'] if use_spm?(options)
+        if options.module_name_configured
+          arguments += ['--module-name', options.module_name]
+        end
+        arguments += ['--']
+      end
+
+      arguments + options.build_tool_arguments
     end
 
     def self.objc_arguments_from_options(options)
       arguments = []
-      if options.xcodebuild_arguments.empty?
+      if options.build_tool_arguments.empty?
         arguments += ['--objc', options.umbrella_header.to_s, '--', '-x',
                       'objective-c', '-isysroot',
                       `xcrun --show-sdk-path --sdk #{options.sdk}`.chomp,