jazzy 0.9.5 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f5a0f16d2a7503e43f28a7eff101228617d44ed4
-  data.tar.gz: e423b906a68d413d3c8e63ce0c7961b5e88da272
+SHA256:
+  metadata.gz: 18e3f122c25c627bb60df82d02b4d788fd1b6bcf0d071eb94c047124fd7a353c
+  data.tar.gz: 26add28c105c85d6ac3c139ac43b068e352cabfbb420c39efb142fbbcef0d662
 SHA512:
-  metadata.gz: ceff92f660c07d63dfd1bf95c6b9928c7ab56fbe8ec8899d37d275248510d2a79c691fc8c83cdb5dfe5516926009ddd10162c48e74898a37613be2cbfd043299
-  data.tar.gz: 21f47afdaadb40618d31c8b0597c698688adc7c2cd64a152d58d3feea0cf47e5607720ac743730bb5b9191cd970c8fdfb63c5270b8775fe6754e813e04a06985
+  metadata.gz: debb129e3cfd568a467c3de5ef98832af900ca3a6307374f25dc94ad3d2fa5243889889b948c4fdc58214e20c74f8223cc5bf922632b7b87a4f71f6dcc28424b
+  data.tar.gz: 5238864991bd821349a9ba76106004aed419675560d26628228a0b640810349a989176705ac1915fdd5d8be33f191b87ca98266fdb43cf7fbfe2be7ef1a7955f

data/.circleci/config.yml

@@ -23,7 +23,7 @@ jobs:
 
   swift:
     macos:
-      xcode: "10.0.0"
+      xcode: "10.2.0"
     environment: *bundler-environment
     # Used to invoke chruby
     shell: *shell
@@ -38,7 +38,7 @@ jobs:
 
   objc:
     macos:
-      xcode: "10.0.0"
+      xcode: "10.2.0"
     environment: *bundler-environment
     # Used to invoke chruby
     shell: *shell
@@ -53,7 +53,7 @@ jobs:
 
   cocoapods:
     macos:
-      xcode: "10.0.0"
+      xcode: "10.2.0"
     environment: *bundler-environment
     # Used to invoke chruby
     shell: *shell

data/CHANGELOG.md

@@ -1,3 +1,157 @@
+## 0.11.2
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* None.
+
+##### Bug Fixes
+
+* Generate Swift docs with Xcode 11 and paths with spaces.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1108](https://github.com/realm/jazzy/issues/1108)
+
+* Reinstate guessing of module name from podspec, broken in 0.11.0.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1109](https://github.com/realm/jazzy/issues/1109)
+
+## 0.11.1
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* None.
+
+##### Bug Fixes
+
+* Don't use SwiftPM if there is an Xcode workspace or project in a non-root
+  directory.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1103](https://github.com/realm/jazzy/issues/1103)
+
+## 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
+
+* The included `sourcekitten` binary is built with Xcode 10.2.  This means
+  it does not run on macOS earlier than 10.14.4 without the *Swift 5 Runtime
+  Support for Command Line Tools* being installed.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+##### Enhancements
+
+* Support CocoaPods 1.6+.  Use the `swift_version[s]` dsl in `--podspec` mode
+  to set the Swift language version.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Show the extension declaration when documenting Swift extensions.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Allow docs title customization.  Include `--module-version` when it is set
+  and support `--title` to fully customize the title.  Pass `{{module_version}}`
+  and `{{docs_title}}` to templates.  
+  [Maximilian Alexander](https://github.com/mbalex99)
+  [John Fairhurst](https://github.com/johnfairh)
+  [#666](https://github.com/realm/jazzy/issues/666)
+  [#411](https://github.com/realm/jazzy/issues/411)
+
+##### Bug Fixes
+
+* Unfold member documentation when linked to from current web page.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#788](https://github.com/realm/jazzy/issues/788)
+
+* Generate docs when there are unusual characters in source pathnames.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1049](https://github.com/realm/jazzy/issues/1049)
+
+* Generate docs for signed modules with Xcode 10.2.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1057](https://github.com/realm/jazzy/issues/1057)
+
+* Use correct module name when only target name is supplied.  
+  [Chris Zielinski](https://github.com/chriszielinski)
+  [#422](https://github.com/realm/jazzy/issues/422)
+
+## 0.9.6
+
+This is (probably) the last release to support Ruby earlier than 2.3.
+This is due to a change in a dependency.
+
+This is (probably) the last release to support macOS earlier than 10.14.4
+without the *Swift 5 Runtime Support for Command Line Tools* package installed.
+This is a consequence of Swift 5 ABI stability.
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Swift 5 support: suppress unwanted newlines and `deinit` declarations.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Update JavaScript libraries: jQuery 3.3.1 (all themes), Lunr 2.3.5,
+  typeahead.js 1.2.1 (`fullwidth` theme only).  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#901](https://github.com/realm/jazzy/issues/901)
+
+* Avoid `clean build` when using the new Xcode build system.  
+  [Norio Nomura](https://github.com/norio-nomura)
+
+##### Bug Fixes
+
+* None.
+
 ## 0.9.5
 
 ##### Breaking

data/CONTRIBUTING.md

@@ -49,7 +49,7 @@ git push
 You'll need push access to the integration specs repo to do this. You can
 request access from one of the maintainers when filing your PR.
 
-You must have Xcode 10.0 installed to build the integration specs.
+You must have Xcode 10.2 installed to build the integration specs.
 
 ## Making changes to SourceKitten
 

data/Gemfile.lock

@@ -1,31 +1,34 @@
 PATH
   remote: .
   specs:
-    jazzy (0.9.5)
-      cocoapods (~> 1.5.3)
-      mustache (~> 1.1.0)
+    jazzy (0.11.2)
+      cocoapods (~> 1.5)
+      mustache (~> 1.1)
       open4
-      redcarpet (~> 3.4.0)
+      redcarpet (~> 3.4)
       rouge (>= 2.0.6, < 4.0)
-      sass (~> 3.6.0)
-      sqlite3 (~> 1.3.13)
+      sassc (~> 2.1)
+      sqlite3 (~> 1.3)
       xcinvoke (~> 0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.0)
-    activesupport (4.2.11)
+    CFPropertyList (3.0.1)
+    activesupport (4.2.11.1)
       i18n (~> 0.7)
       minitest (~> 5.1)
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    algoliasearch (1.27.0)
+      httpclient (~> 2.8, >= 2.8.3)
+      json (>= 1.5.1)
     ast (2.4.0)
     atomos (0.1.3)
     bacon (1.2.0)
-    claide (1.0.2)
+    claide (1.0.3)
     claide-plugins (0.9.2)
       cork
       nap
@@ -33,55 +36,58 @@ GEM
     clintegracon (0.7.0)
       colored (~> 1.2)
       diffy
-    cocoapods (1.5.3)
+    cocoapods (1.8.0)
       activesupport (>= 4.0.2, < 5)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.5.3)
-      cocoapods-deintegrate (>= 1.0.2, < 2.0)
-      cocoapods-downloader (>= 1.2.0, < 2.0)
+      cocoapods-core (= 1.8.0)
+      cocoapods-deintegrate (>= 1.0.3, < 2.0)
+      cocoapods-downloader (>= 1.2.2, < 2.0)
       cocoapods-plugins (>= 1.0.0, < 2.0)
       cocoapods-search (>= 1.0.0, < 2.0)
       cocoapods-stats (>= 1.0.0, < 2.0)
-      cocoapods-trunk (>= 1.3.0, < 2.0)
+      cocoapods-trunk (>= 1.4.0, < 2.0)
       cocoapods-try (>= 1.1.0, < 2.0)
       colored2 (~> 3.1)
       escape (~> 0.0.4)
-      fourflusher (~> 2.0.1)
+      fourflusher (>= 2.3.0, < 3.0)
       gh_inspector (~> 1.0)
-      molinillo (~> 0.6.5)
+      molinillo (~> 0.6.6)
       nap (~> 1.0)
-      ruby-macho (~> 1.1)
-      xcodeproj (>= 1.5.7, < 2.0)
-    cocoapods-core (1.5.3)
+      ruby-macho (~> 1.4)
+      xcodeproj (>= 1.11.1, < 2.0)
+    cocoapods-core (1.8.0)
       activesupport (>= 4.0.2, < 6)
+      algoliasearch (~> 1.0)
+      concurrent-ruby (~> 1.0)
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
-    cocoapods-deintegrate (1.0.2)
+    cocoapods-deintegrate (1.0.4)
     cocoapods-downloader (1.2.2)
     cocoapods-plugins (1.0.0)
       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)
     colored (1.2)
     colored2 (3.1.2)
-    concurrent-ruby (1.1.4)
+    concurrent-ruby (1.1.5)
     cork (0.3.0)
       colored2 (~> 3.1)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
-    danger (5.11.1)
+    danger (6.0.9)
       claide (~> 1.0)
       claide-plugins (>= 0.9.2)
       colored2 (~> 3.1)
       cork (~> 0.1)
       faraday (~> 0.9)
-      faraday-http-cache (~> 1.0)
+      faraday-http-cache (~> 2.0)
       git (~> 1.5)
-      kramdown (~> 1.5)
+      kramdown (~> 2.0)
+      kramdown-parser-gfm (~> 1.0)
       no_proxy_fix
       octokit (~> 4.7)
       terminal-table (~> 1)
@@ -89,49 +95,50 @@ GEM
     escape (0.0.4)
     faraday (0.15.4)
       multipart-post (>= 1.2, < 3)
-    faraday-http-cache (1.3.1)
+    faraday-http-cache (2.0.0)
       faraday (~> 0.8)
-    ffi (1.10.0)
-    fourflusher (2.0.1)
+    ffi (1.11.1)
+    fourflusher (2.3.1)
     fuzzy_match (2.0.4)
     gh_inspector (1.1.3)
     git (1.5.0)
-    hashdiff (0.3.8)
+    hashdiff (1.0.0)
+    httpclient (2.8.3)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    kramdown (1.17.0)
+    json (2.2.0)
+    kramdown (2.1.0)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     liferaft (0.0.6)
     metaclass (0.0.4)
-    minitest (5.11.3)
-    mocha (1.8.0)
+    minitest (5.12.0)
+    mocha (1.9.0)
       metaclass (~> 0.0.1)
     mocha-on-bacon (0.2.3)
       mocha (>= 0.13.0)
     molinillo (0.6.6)
-    multipart-post (2.0.0)
+    multipart-post (2.1.1)
     mustache (1.1.0)
     nanaimo (0.2.6)
     nap (1.1.0)
     netrc (0.11.0)
     no_proxy_fix (0.1.2)
-    octokit (4.13.0)
+    octokit (4.14.0)
       sawyer (~> 0.8.0, >= 0.5.3)
     open4 (1.3.4)
-    parallel (1.13.0)
-    parser (2.6.0.0)
+    parallel (1.17.0)
+    parser (2.6.4.1)
       ast (~> 2.4.0)
     powerpack (0.1.2)
     prettybacon (0.0.2)
       bacon (~> 1.2)
-    public_suffix (3.0.3)
+    public_suffix (4.0.1)
     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.3.0)
+    redcarpet (3.5.0)
+    rouge (3.11.0)
     rubocop (0.49.0)
       parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)
@@ -139,31 +146,28 @@ GEM
       rainbow (>= 1.99.1, < 3.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
-    ruby-macho (1.3.1)
-    ruby-progressbar (1.10.0)
-    safe_yaml (1.0.4)
-    sass (3.6.0)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-    sawyer (0.8.1)
-      addressable (>= 2.3.5, < 2.6)
-      faraday (~> 0.8, < 1.0)
-    sqlite3 (1.3.13)
+    ruby-macho (1.4.0)
+    ruby-progressbar (1.10.1)
+    safe_yaml (1.0.5)
+    sassc (2.2.1)
+      ffi (~> 1.9)
+    sawyer (0.8.2)
+      addressable (>= 2.3.5)
+      faraday (> 0.8, < 2.0)
+    sqlite3 (1.4.1)
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    unicode-display_width (1.4.1)
-    webmock (3.5.1)
+    unicode-display_width (1.6.0)
+    webmock (3.7.5)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
-      hashdiff
+      hashdiff (>= 0.4.0, < 2.0.0)
     xcinvoke (0.3.0)
       liferaft (~> 0.0.6)
-    xcodeproj (1.7.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,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 \
@@ -233,9 +245,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 +283,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 +298,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.
@@ -318,3 +356,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"