jazzy 0.9.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 319a5e064f71871c4311e5b60e6b2a45a85d2c99
-  data.tar.gz: 6cbebd00f828e1ef1a08382a2af92e0723126cbd
+  metadata.gz: ded8d78313e2fcab8ead87a65f4cf9f35d2584a1
+  data.tar.gz: eb426a586c8fce20e5e87c9ccbaac0466bd10d8d
 SHA512:
-  metadata.gz: 9bd0c57811ffaaf3b0f1dbf5b15441c3acc461024ac1ce5934faa78d82d049d612c7b5d93970b8a532ecbc71beadb3735d6bf53f264c01a128cbf2cc54654c80
-  data.tar.gz: de4b36d41306cc0746f21154838793efc3e95b56d86bf4ad26c911f371db0b83318b3db07e770c223007fc43c327eb9deabdc8e89cd21d3049d87c45872cb345
+  metadata.gz: 6694288ef466e3f3fa62508ae1905cbb1c76cf9a0a010b46ca167d08aa2d3dbc6951d306bcfb48102fe36758e8f89a45d429a992ac934b2dbe924198f3380891
+  data.tar.gz: 56ba55fa32962a163b739455a6f1965aead62019582e3cb8ca81e39f8d26df4723965ab5029fca2db0a3fecf62c11d3c948e93a987ae22d2826d3f67e32e8d02

data/.circleci/config.yml

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

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## 0.9.2
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Add a new 'jony' theme similar to the 2017 Apple documentation style.  
+  [Harshil Shah](https://github.com/HarshilShah)
+
+* Add the ability to limit documentation to certain files by passing in an
+  `-i`/`--include` argument.  
+  [Nick Fox](https://github.com/nicholasffox)
+  [#949](https://github.com/realm/jazzy/issues/949)
+
+* Improve Swift declarations to look more like the Xcode Quick Help version,
+  for example including `{ get set }`, and include all attributes.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#768](https://github.com/realm/jazzy/issues/768)
+  [#591](https://github.com/realm/jazzy/issues/591)
+
+##### Bug Fixes
+
+* Preserve `MARK` comment headings associated with extensions and enum cases.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Fix issue where Overview items were invalidly being referenced with NULL
+  types in the generated Dash docset index.  
+  [Andrew De Ponte](https://github.com/cyphactor)
+
+* Don't display FIXME or TODO comments as section markers.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#658](https://github.com/realm/jazzy/issues/658)
+
 ## 0.9.1
 
 ##### 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 9.2 installed to build the integration specs.
+You must have Xcode 9.3 installed to build the integration specs.
 
 ## Making changes to SourceKitten
 

data/Dangerfile

@@ -24,5 +24,5 @@ end
 
 # Non-trivial amounts of app changes without tests
 if git.lines_of_code > 50 && has_app_changes && !has_test_changes
-    warn "This PR may need tests."    
+    warn "This PR may need tests."
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.9.1)
+    jazzy (0.9.2)
       cocoapods (~> 1.0)
       mustache (~> 0.99)
       open4
@@ -14,7 +14,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (2.3.6)
+    CFPropertyList (3.0.0)
     activesupport (4.2.10)
       i18n (~> 0.7)
       minitest (~> 5.1)
@@ -22,7 +22,8 @@ GEM
       tzinfo (~> 1.1)
     addressable (2.5.2)
       public_suffix (>= 2.0.2, < 4.0)
-    ast (2.3.0)
+    ast (2.4.0)
+    atomos (0.1.2)
     bacon (1.2.0)
     claide (1.0.2)
     claide-plugins (0.9.2)
@@ -32,31 +33,31 @@ GEM
     clintegracon (0.7.0)
       colored (~> 1.2)
       diffy
-    cocoapods (1.3.1)
+    cocoapods (1.5.0)
       activesupport (>= 4.0.2, < 5)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.3.1)
-      cocoapods-deintegrate (>= 1.0.1, < 2.0)
-      cocoapods-downloader (>= 1.1.3, < 2.0)
+      cocoapods-core (= 1.5.0)
+      cocoapods-deintegrate (>= 1.0.2, < 2.0)
+      cocoapods-downloader (>= 1.2.0, < 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.2.0, < 2.0)
+      cocoapods-trunk (>= 1.3.0, < 2.0)
       cocoapods-try (>= 1.1.0, < 2.0)
       colored2 (~> 3.1)
       escape (~> 0.0.4)
       fourflusher (~> 2.0.1)
       gh_inspector (~> 1.0)
-      molinillo (~> 0.5.7)
+      molinillo (~> 0.6.5)
       nap (~> 1.0)
       ruby-macho (~> 1.1)
-      xcodeproj (>= 1.5.1, < 2.0)
-    cocoapods-core (1.3.1)
+      xcodeproj (>= 1.5.7, < 2.0)
+    cocoapods-core (1.5.0)
       activesupport (>= 4.0.2, < 6)
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
-    cocoapods-deintegrate (1.0.1)
-    cocoapods-downloader (1.1.3)
+    cocoapods-deintegrate (1.0.2)
+    cocoapods-downloader (1.2.0)
     cocoapods-plugins (1.0.0)
       nap
     cocoapods-search (1.0.0)
@@ -72,7 +73,7 @@ GEM
       colored2 (~> 3.1)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
-    danger (5.5.3)
+    danger (5.5.12)
       claide (~> 1.0)
       claide-plugins (>= 0.9.2)
       colored2 (~> 3.1)
@@ -86,51 +87,51 @@ GEM
       terminal-table (~> 1)
     diffy (3.2.0)
     escape (0.0.4)
-    faraday (0.13.1)
+    faraday (0.15.0)
       multipart-post (>= 1.2, < 3)
     faraday-http-cache (1.3.1)
       faraday (~> 0.8)
-    ffi (1.9.18)
+    ffi (1.9.23)
     fourflusher (2.0.1)
     fuzzy_match (2.0.4)
-    gh_inspector (1.0.3)
+    gh_inspector (1.1.3)
     git (1.3.0)
     hashdiff (0.3.7)
-    i18n (0.9.1)
+    i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    kramdown (1.15.0)
+    kramdown (1.16.2)
     liferaft (0.0.6)
     metaclass (0.0.4)
-    minitest (5.11.1)
-    mocha (1.3.0)
+    minitest (5.11.3)
+    mocha (1.5.0)
       metaclass (~> 0.0.1)
     mocha-on-bacon (0.2.3)
       mocha (>= 0.13.0)
-    molinillo (0.5.7)
+    molinillo (0.6.5)
     multipart-post (2.0.0)
     mustache (0.99.8)
-    nanaimo (0.2.3)
+    nanaimo (0.2.5)
     nap (1.1.0)
     netrc (0.11.0)
     no_proxy_fix (0.1.2)
-    octokit (4.7.0)
+    octokit (4.8.0)
       sawyer (~> 0.8.0, >= 0.5.3)
     open4 (1.3.4)
-    parallel (1.12.0)
-    parser (2.4.0.0)
-      ast (~> 2.2)
+    parallel (1.12.1)
+    parser (2.5.1.0)
+      ast (~> 2.4.0)
     powerpack (0.1.1)
     prettybacon (0.0.2)
       bacon (~> 1.2)
-    public_suffix (3.0.0)
+    public_suffix (3.0.2)
     rainbow (2.2.2)
       rake
     rake (10.5.0)
-    rb-fsevent (0.10.2)
+    rb-fsevent (0.10.3)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
     redcarpet (3.4.0)
-    rouge (3.1.0)
+    rouge (3.1.1)
     rubocop (0.49.0)
       parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)
@@ -141,7 +142,7 @@ GEM
     ruby-macho (1.1.0)
     ruby-progressbar (1.9.0)
     safe_yaml (1.0.4)
-    sass (3.5.5)
+    sass (3.5.6)
       sass-listen (~> 4.0.0)
     sass-listen (4.0.0)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -153,20 +154,21 @@ GEM
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     thread_safe (0.3.6)
-    tzinfo (1.2.4)
+    tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    unicode-display_width (1.3.0)
-    webmock (3.1.0)
+    unicode-display_width (1.3.2)
+    webmock (3.3.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff
     xcinvoke (0.3.0)
       liferaft (~> 0.0.6)
-    xcodeproj (1.5.4)
-      CFPropertyList (~> 2.3.3)
+    xcodeproj (1.5.7)
+      CFPropertyList (>= 2.3.3, < 4.0)
+      atomos (~> 0.1.2)
       claide (>= 1.0.2, < 2.0)
       colored2 (~> 3.1)
-      nanaimo (~> 0.2.3)
+      nanaimo (~> 0.2.4)
 
 PLATFORMS
   ruby

data/README.md

@@ -35,6 +35,10 @@ 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.
+
 ## Usage
 
 Run `jazzy` from your command line. Run `jazzy -h` for a list of additional options.
@@ -139,11 +143,11 @@ jazzy \
 
 ### Themes
 
-Two themes are provided with jazzy: `apple` (default) and `fullwidth`.
-
-Here's an example built with `apple`: <https://realm.io/docs/swift/latest/api/>
+Three themes are provided with jazzy: `apple` (default), `fullwidth` and `jony`.
 
-Here's an example built with `fullwidth`: <http://reduxkit.github.io/ReduxKit/>
+* `apple` example: <https://realm.io/docs/swift/latest/api/>
+* `fullwidth` example: <https://reduxkit.github.io/ReduxKit/>
+* `jony` example: <https://harshilshah.github.io/IGListKit/>
 
 You can specify which theme to use by passing in the `--theme` option. You can
 also provide your own custom theme by passing in the path to your theme
@@ -193,21 +197,28 @@ include declarations with a lower access level, set the `--min-acl` flag to `int
 In Objective-C mode, Jazzy documents all declarations found in the `--umbrella-header`
 header file and any other header files included by it.
 
-You can then prevent some of these declarations from being documented using `--exclude`
-or `:nodoc:`.
+You can control exactly which declarations should be documented using `--exclude`,
+`--include`, or `:nodoc:`.
 
-The `--exclude` flag lists source files to omit from the documentation. Entries in the
-list can be absolute pathnames beginning with `/` or relative pathnames. Relative
-pathnames are interpreted relative to the directory from where you run `jazzy` or, if the
-exclude flag is set in the config file, relative to the directory containing the config
-file. Entries in the list can match multiple files using `*` to match any number of
-characters including `/`.  For example:
-* `jazzy --exclude=/Users/fred/project/Sources/Secret.swift` -- exclude a specific file
+The `--include` and `--exclude` flags list source files that should be included/excluded
+respectively in the documentation. Entries in the list can be absolute pathnames beginning
+with `/` or relative pathnames. Relative pathnames are interpreted relative to the
+directory from where you run `jazzy` or, if the flags are set in the config file, relative
+to the directory containing the config file. Entries in the list can match multiple files
+using `*` to match any number of characters including `/`.  For example:
+* `jazzy --include=/Users/fred/project/Sources/Secret.swift` -- include a specific file
 * `jazzy --exclude=/*/Internal*` -- exclude all files with names that begin with *Internal*
   and any files under any directory with a name beginning *Internal*.
 * `jazzy --exclude=Impl1/*,Impl2/*` -- exclude all files under the directories *Impl1* and
   *Impl2* found in the current directory.
 
+Note that the `--include` option is applied before the `--exclude` option. For example:
+
+* `jazzy --include=/*/Internal* --exclude=Impl1/*,Impl2/*` -- include all files with names
+  that begin with *Internal* and any files under any directory with a name beginning
+  *Internal*, **except** for those under the directories *Impl1* and *Impl2* found in the
+  current directory
+
 Declarations with a documentation comment containing `:nodoc:` are excluded from the
 documentation.
 

data/Rakefile

@@ -106,9 +106,6 @@ begin
       `swift build -c release -Xswiftc -static-stdlib`
     end
     FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
-    system 'install_name_tool', '-delete_rpath',
-           (Pathname(`xcrun -find swift`) + '../../lib/swift/macosx').to_s,
-           'bin/sourcekitten'
   end
 
 rescue LoadError, NameError => e

data/lib/jazzy/config.rb

@@ -167,6 +167,15 @@ module Jazzy
         Array(files).map { |f| expand_path(f).to_s }
       end
 
+    config_attr :included_files,
+      command_line: ['-i', '--include filepath1,filepath2,…filepathN', Array],
+      description: 'Source file pathnames to be included in documentation. '\
+                   'Supports wildcards.',
+      default: [],
+      parse: ->(files) do
+        Array(files).map { |f| expand_path(f).to_s }
+      end
+
     config_attr :swift_version,
       command_line: '--swift-version VERSION',
       default: nil,
@@ -302,10 +311,10 @@ module Jazzy
       default: ''
 
     config_attr :theme_directory,
-      command_line: '--theme [apple | fullwidth | DIRPATH]',
+      command_line: '--theme [apple | fullwidth | jony | DIRPATH]',
       description: "Which theme to use. Specify either 'apple' (default), "\
-                   "'fullwidth' or the path to your mustache templates and " \
-                   'other assets for a custom theme.',
+                   "'fullwidth', 'jony' or the path to your mustache " \
+                   'templates and other assets for a custom theme.',
       default: 'apple',
       parse: ->(t) do
         if %w[apple fullwidth].include?(t)

data/lib/jazzy/gem_version.rb

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

data/lib/jazzy/source_declaration.rb

@@ -49,6 +49,14 @@ module Jazzy
       namespace_path.map(&:name).join('.')
     end
 
+    # :name doesn't include any generic type params.
+    # This regexp matches any generic type params in parent names.
+    def fully_qualified_name_regexp
+      Regexp.new(namespace_path.map(&:name)
+                               .map { |n| Regexp.escape(n) }
+                               .join('(?:<.*?>)?\.'))
+    end
+
     # If this declaration is an objc category, returns an array with the name
     # of the extended objc class and the category name itself, i.e.
     # ["NSString", "MyMethods"], nil otherwise.

data/lib/jazzy/source_declaration/type.rb

@@ -5,7 +5,7 @@ module Jazzy
     # rubocop:disable Metrics/ClassLength
     class Type
       def self.all
-        TYPES.keys.map { |k| new(k) }
+        TYPES.keys.map { |k| new(k) }.reject { |t| t.name.nil? }
       end
 
       attr_reader :kind
@@ -43,9 +43,22 @@ module Jazzy
         url_name.pluralize
       end
 
+      def objc_mark?
+        kind == 'sourcekitten.source.lang.objc.mark'
+      end
+
+      # covers MARK: TODO: FIXME: comments
+      def swift_mark?
+        kind == 'source.lang.swift.syntaxtype.comment.mark'
+      end
+
       def mark?
-        kind == 'source.lang.swift.syntaxtype.comment.mark' ||
-          kind == 'sourcekitten.source.lang.objc.mark'
+        objc_mark? || swift_mark?
+      end
+
+      # mark that should start a new task section
+      def task_mark?(name)
+        objc_mark? || (swift_mark? && name.start_with?('MARK: '))
       end
 
       def objc_enum?
@@ -132,6 +145,11 @@ module Jazzy
           dash: 'Guide',
         }.freeze,
 
+        'Overview' => {
+          jazzy: nil,
+          dash: 'Section',
+        }.freeze,
+
         # Objective-C
         'sourcekitten.source.lang.objc.decl.unexposed' => {
           jazzy: 'Unexposed',