jazzy 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bfdc8ff94daa57717cca49f094c0844e887966c7
-  data.tar.gz: 4476ebbceab1a7f423718385181b5d7c8ec6c9e3
+  metadata.gz: 371a8d34a746d3593ff47191c1ae36f57c93310f
+  data.tar.gz: 419ab9cf9fb43c6434504ccad2aaf6c4a0a46aa4
 SHA512:
-  metadata.gz: 07c5389be619f4e5739cb9afc114b423fa9dbad9217d47e91a5538aaa54c89eb0fd6d27b286812ace6ee82ca4873f01bc6c770cadf3e1231461741f112047be2
-  data.tar.gz: ed8b0bd4d88757e4eeda790f50debc4ff74356ff4812312991b78148462738b4692a469d2ad896adf35a8e8589faad95ddd831962ff5f59d715557d65a6e5ec5
+  metadata.gz: bbee289354b3e4ea2e2874af3bf97040605658839ad9a28be5821f23f4ea9369492eff7f6b00de5106a4945924142643670ead0723d2b163b071e04c8d83365b
+  data.tar.gz: 5c9c31bafd32bf396285c74a0bbbea2984f274a45cbe3dab761a349db56e2c04b4bea7a1deff133b8cb409f2ab3becc7d2cde176e3cc99dc3b8f36b6e1f5a7f3

data/.travis.yml

@@ -1,16 +1,17 @@
 language: objective-c
-osx_image: xcode6.4
-cache: bundler
 branches:
   only:
     - master
-rvm:
-  - system
-before_install:
-  - sudo gem install bundler
-  - git submodule update --init --recursive
-script:
-  - bundle exec rake spec
+git:
+  submodules: false
+before_install: git submodule update --init --recursive
+script: bundle exec rake spec
 notifications:
   email: false
   slack: realmio:vPdpsG9NLDo2DNlbqtcMAQuE
+matrix:
+  include:
+    - osx_image: xcode6.4
+      env: TRAVIS_SWIFT_VERSION=1.2
+    - osx_image: xcode7
+      env: TRAVIS_SWIFT_VERSION=2.0

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## 0.3.0
+
+##### Breaking
+
+* `--swift-version` now defaults to 2.0 instead of 1.2.  
+  [JP Simard](https://github.com/jpsim)
+
+##### Enhancements
+
+* Now supports Swift 2.0 (previous Swift versions are still supported).  
+  [JP Simard](https://github.com/jpsim)
+  [Samuel Giddins](https://github.com/segiddins)
+
+* Declarations can now be grouped by custom categories defined in a JSON or YAML
+  file passed to `--categories`.  
+  [pcantrell](https://github.com/pcantrell)
+
+##### Bug Fixes
+
+* "View on GitHub" is now only generated if a GitHub URL is specified.  
+  [mbogh](https://github.com/mbogh)
+  [#244](https://github.com/realm/jazzy/issues/244)
+
+* Empty extensions are no longer documented.  
+  [pcantrell](https://github.com/pcantrell)
+
+* Undocumented enum cases are now supported.  
+  [JP Simard](https://github.com/jpsim)
+  [#74](https://github.com/realm/jazzy/issues/74)
+
+
 ## 0.2.4
 
 ##### Breaking

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.2.4)
+    jazzy (0.3.0)
       cocoapods (~> 0.38)
       mustache (~> 0.99)
       open4
@@ -14,7 +14,7 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (4.2.3)
+    activesupport (4.2.4)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
@@ -47,13 +47,13 @@ GEM
       activesupport (>= 3.2.15)
       fuzzy_match (~> 2.0.4)
       nap (~> 0.8.0)
-    cocoapods-downloader (0.9.1)
+    cocoapods-downloader (0.9.3)
     cocoapods-plugins (0.4.2)
       nap
     cocoapods-stats (0.5.3)
       nap (~> 0.8)
-    cocoapods-trunk (0.6.1)
-      nap (>= 0.8)
+    cocoapods-trunk (0.6.4)
+      nap (>= 0.8, < 2.0)
       netrc (= 0.7.8)
     cocoapods-try (0.4.5)
     colored (1.2)
@@ -66,7 +66,7 @@ GEM
     json (1.8.3)
     liferaft (0.0.4)
     metaclass (0.0.4)
-    minitest (5.7.0)
+    minitest (5.8.0)
     mocha (1.1.0)
       metaclass (~> 0.0.1)
     mocha-on-bacon (0.2.2)
@@ -94,7 +94,7 @@ GEM
       ruby-progressbar (~> 1.4)
     ruby-progressbar (1.6.0)
     safe_yaml (1.0.4)
-    sass (3.4.16)
+    sass (3.4.18)
     slop (3.6.0)
     sqlite3 (1.3.10)
     thread_safe (0.3.5)

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>15A235d</string>
+	<string>15A279b</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -20,22 +20,26 @@
 	<string>1.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
+	<key>CFBundleSupportedPlatforms</key>
+	<array>
+		<string>MacOSX</string>
+	</array>
 	<key>CFBundleVersion</key>
 	<string>1</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>14D125</string>
+	<string>15A244e</string>
 	<key>DTSDKName</key>
-	<string>macosx10.10</string>
+	<string>macosx10.11</string>
 	<key>DTXcode</key>
-	<string>0640</string>
+	<string>0700</string>
 	<key>DTXcodeBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2014 Carthage. All rights reserved.</string>
 </dict>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/{LlamaKit.framework → Result.framework}/Versions/A/Resources/Info.plist

@@ -3,45 +3,44 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>15A235d</string>
+	<string>15A279b</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
-	<string>LlamaKit</string>
+	<string>Result</string>
 	<key>CFBundleIdentifier</key>
-	<string>net.robnapier.LlamaKit</string>
+	<string>com.antitypical.Result</string>
 	<key>CFBundleInfoDictionaryVersion</key>
 	<string>6.0</string>
 	<key>CFBundleName</key>
-	<string>LlamaKit</string>
+	<string>Result</string>
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>1.0</string>
+	<string>0.0.1</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
+	<key>CFBundleSupportedPlatforms</key>
+	<array>
+		<string>MacOSX</string>
+	</array>
 	<key>CFBundleVersion</key>
 	<string>1</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>14D125</string>
+	<string>15A244e</string>
 	<key>DTSDKName</key>
-	<string>macosx10.10</string>
+	<string>macosx10.11</string>
 	<key>DTXcode</key>
-	<string>0640</string>
+	<string>0700</string>
 	<key>DTXcodeBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>NSHumanReadableCopyright</key>
-	<string>Copyright © 2014 Rob Napier. All rights reserved.</string>
-	<key>UIDeviceFamily</key>
-	<array>
-		<integer>1</integer>
-		<integer>2</integer>
-	</array>
+	<string>Copyright © 2015 Rob Rix. All rights reserved.</string>
 </dict>
 </plist>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>15A235d</string>
+	<string>15A279b</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -20,22 +20,26 @@
 	<string>1.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
+	<key>CFBundleSupportedPlatforms</key>
+	<array>
+		<string>MacOSX</string>
+	</array>
 	<key>CFBundleVersion</key>
 	<string>1</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>14D125</string>
+	<string>15A244e</string>
 	<key>DTSDKName</key>
-	<string>macosx10.10</string>
+	<string>macosx10.11</string>
 	<key>DTXcode</key>
-	<string>0640</string>
+	<string>0700</string>
 	<key>DTXcodeBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>UIDeviceFamily</key>
 	<array>
 		<integer>1</integer>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>15A235d</string>
+	<string>15A279b</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -20,22 +20,26 @@
 	<string>1.0.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
+	<key>CFBundleSupportedPlatforms</key>
+	<array>
+		<string>MacOSX</string>
+	</array>
 	<key>CFBundleVersion</key>
 	<string>1</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>14D125</string>
+	<string>15A244e</string>
 	<key>DTSDKName</key>
-	<string>macosx10.10</string>
+	<string>macosx10.11</string>
 	<key>DTXcode</key>
-	<string>0640</string>
+	<string>0700</string>
 	<key>DTXcodeBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2014 JP Simard. All rights reserved.</string>
 </dict>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>15A235d</string>
+	<string>15A279b</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,25 +17,29 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.4.4</string>
+	<string>0.5.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
+	<key>CFBundleSupportedPlatforms</key>
+	<array>
+		<string>MacOSX</string>
+	</array>
 	<key>CFBundleVersion</key>
 	<string>1</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>14D125</string>
+	<string>15A244e</string>
 	<key>DTSDKName</key>
-	<string>macosx10.10</string>
+	<string>macosx10.11</string>
 	<key>DTXcode</key>
-	<string>0640</string>
+	<string>0700</string>
 	<key>DTXcodeBuild</key>
-	<string>6E35b</string>
+	<string>7A192o</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2015 SourceKitten. All rights reserved.</string>
 </dict>

data/lib/jazzy/config.rb

@@ -30,6 +30,7 @@ module Jazzy
     attr_accessor :docset_path
     attr_accessor :source_directory
     attr_accessor :excluded_files
+    attr_accessor :custom_categories
     attr_accessor :template_directory
     attr_accessor :swift_version
     attr_accessor :assets_directory
@@ -49,8 +50,9 @@ module Jazzy
       self.skip_undocumented = false
       self.source_directory = Pathname.pwd
       self.excluded_files = []
+      self.custom_categories = {}
       self.template_directory = Pathname(__FILE__).parent + 'templates'
-      self.swift_version = '1.2'
+      self.swift_version = '2.0'
       self.assets_directory = Pathname(__FILE__).parent + 'assets'
     end
 
@@ -198,6 +200,11 @@ module Jazzy
           config.excluded_files = files.map { |f| File.expand_path(f) }
         end
 
+        opt.on('--categories file',
+               'JSON or YAML file with custom groupings') do |file|
+          config.custom_categories = parse_config_file(file)
+        end
+
         opt.on('-v', '--version', 'Print version number') do
           puts 'jazzy version: ' + Jazzy::VERSION
           exit
@@ -217,6 +224,14 @@ module Jazzy
       config
     end
 
+    def self.parse_config_file(file)
+      case File.extname(file)
+      when '.json'         then JSON.parse(File.read(file))
+      when '.yaml', '.yml' then YAML.load(File.read(file))
+      else raise "Config file must be .yaml or .json, but got #{file.inspect}"
+      end
+    end
+
     #-------------------------------------------------------------------------#
 
     # @!group Singleton

data/lib/jazzy/doc.rb

@@ -10,6 +10,25 @@ module Jazzy
   class Doc < Mustache
     self.template_name = 'doc'
 
+    ############################################################################
+    # TODO: Remove shortly (kept for backwards compatibility)
+    #
+    def date
+      # Fake date is used to keep integration tests consistent
+      ENV['JAZZY_FAKE_DATE'] || DateTime.now.strftime('%Y-%m-%d')
+    end
+
+    def year
+      # Fake date is used to keep integration tests consistent
+      if ENV['JAZZY_FAKE_DATE']
+        ENV['JAZZY_FAKE_DATE'][0..3]
+      else
+        DateTime.now.strftime('%Y')
+      end
+    end
+    #
+    ############################################################################
+
     def copyright
       config = Config.instance
       copyright = config.copyright || (

data/lib/jazzy/doc_builder.rb

@@ -31,9 +31,12 @@ module Jazzy
       docs.map do |doc|
         {
           section: doc.name,
-          children: doc.children.sort_by(&:name).map do |child|
-            { name: child.name, url: child.url }
-          end,
+          children: doc.children
+              .sort_by(&:name)
+              .sort_by(&:nav_order)
+              .map do |child|
+                { name: child.name, url: child.url }
+              end,
         }
       end
     end
@@ -70,25 +73,26 @@ module Jazzy
     # @param [Config] options Build options
     # @param [Array] doc_structure @see #doc_structure_for_docs
     def self.build_docs(output_dir, docs, source_module)
-      each_doc(output_dir, docs) do |doc, path, depth|
+      each_doc(output_dir, docs) do |doc, path|
         prepare_output_dir(path.parent, false)
-        path_to_root = ['../'].cycle(depth).to_a.join('')
+        depth = path.relative_path_from(output_dir).each_filename.count - 1
+        path_to_root = '../' * depth
         path.open('w') do |file|
           file.write(document(source_module, doc, path_to_root))
         end
       end
     end
 
-    def self.each_doc(output_dir, docs, depth = 0, &block)
+    def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
         next if doc.name != 'index' && doc.children.count == 0
-        path = output_dir + "#{doc.name}.html"
-        block.call(doc, path, depth)
+        # Assuming URL is relative to documentation root:
+        path = output_dir + (doc.url || "#{doc.name}.html")
+        block.call(doc, path)
         next if doc.name == 'index'
         each_doc(
-          output_dir + doc.name,
+          output_dir,
           doc.children,
-          depth + 1,
           &block
         )
       end
@@ -183,7 +187,9 @@ module Jazzy
       doc[:structure] = source_module.doc_structure
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
-      doc[:github_url] = source_module.github_url.to_s
+      # TODO: Remove shortly (kept for backwards compatibility)
+      doc[:author_website] = source_module.author_url
+      doc[:github_url] = source_module.github_url
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:hide_name] = true
@@ -287,7 +293,9 @@ module Jazzy
       doc[:tasks] = render_tasks(source_module, doc_model.children)
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
-      doc[:github_url] = source_module.github_url.to_s
+      # TODO: Remove shortly (kept for backwards compatibility)
+      doc[:author_website] = source_module.author_url.to_s
+      doc[:github_url] = source_module.github_url
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc.render

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.2.4' unless defined? Jazzy::VERSION
+  VERSION = '0.3.0' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/jazzy_markdown.rb

@@ -19,6 +19,59 @@ module Jazzy
       "<h#{header_level} id='#{text_slug}'>#{text}</h#{header_level}>\n"
     end
 
+    SPECIAL_LIST_TYPES = %w(Attention
+                            Author
+                            Authors
+                            Bug
+                            Complexity
+                            Copyright
+                            Date
+                            Experiment
+                            Important
+                            Invariant
+                            Note
+                            Parameter
+                            Postcondition
+                            Precondition
+                            Remark
+                            Requires
+                            Returns
+                            See
+                            SeeAlso
+                            Since
+                            TODO
+                            Throws
+                            Version
+                            Warning).freeze
+
+    # rubocop:disable RegexpLiteral
+    SPECIAL_LIST_TYPE_REGEX = %r{
+      \A\s* # optional leading spaces
+      (<p>\s*)? # optional opening p tag
+      # any one of our special list types
+      (#{SPECIAL_LIST_TYPES.map(&Regexp.method(:escape)).join('|')})
+      [\s:] # followed by either a space or a colon
+    }ix
+    # rubocop:enable RegexpLiteral
+
+    ELIDED_LI_TOKEN = '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'.freeze
+
+    def list_item(text, _list_type)
+      return ELIDED_LI_TOKEN if text =~ SPECIAL_LIST_TYPE_REGEX
+      str = '<li>'
+      str << text.strip
+      str << "</li>\n"
+    end
+
+    def list(text, list_type)
+      elided = text.gsub!(ELIDED_LI_TOKEN, '')
+      return if text =~ /\A\s*\Z/ && elided
+      str = "\n"
+      str << (list_type == :ordered ? "<ol>\n" : "<ul>\n")
+      str << text
+      str << (list_type == :ordered ? "</ol>\n" : "</ul>\n")
+    end
+
     OPTIONS = {
       autolink: true,
       fenced_code_blocks: true,

data/lib/jazzy/source_declaration.rb

@@ -23,6 +23,7 @@ module Jazzy
     attr_accessor :access_control_level
     attr_accessor :start_line
     attr_accessor :end_line
+    attr_accessor :nav_order
 
     def overview
       "#{abstract}\n\n#{discussion}".strip

data/lib/jazzy/source_declaration/type.rb

@@ -31,6 +31,14 @@ module Jazzy
         kind == 'source.lang.swift.syntaxtype.comment.mark'
       end
 
+      def enum_case?
+        kind == 'source.lang.swift.decl.enumcase'
+      end
+
+      def enum_element?
+        kind == 'source.lang.swift.decl.enumelement'
+      end
+
       def should_document?
         declaration? && !param?
       end
@@ -39,6 +47,10 @@ module Jazzy
         kind =~ /^source\.lang\.swift\.decl\..*/
       end
 
+      def extension?
+        kind =~ /^source\.lang\.swift\.decl\.extension.*/
+      end
+
       def param?
         # SourceKit strangely categorizes initializer parameters as local
         # variables, so both kinds represent a parameter in jazzy.
@@ -84,6 +96,10 @@ module Jazzy
           jazzy: 'Global Variable',
           dash: 'Global',
         }.freeze,
+        'source.lang.swift.decl.enumcase' => {
+          jazzy: 'Enum Case',
+          dash: 'Case',
+        }.freeze,
         'source.lang.swift.decl.enumelement' => {
           jazzy: 'Enum Element',
           dash: 'Element',
@@ -96,6 +112,18 @@ module Jazzy
           jazzy: 'Extension',
           dash: 'Extension',
         }.freeze,
+        'source.lang.swift.decl.extension.class' => {
+          jazzy: 'Class Extension',
+          dash: 'Extension',
+        }.freeze,
+        'source.lang.swift.decl.extension.enum' => {
+          jazzy: 'Enum Extension',
+          dash: 'Extension',
+        }.freeze,
+        'source.lang.swift.decl.extension.protocol' => {
+          jazzy: 'Protocol Extension',
+          dash: 'Extension',
+        }.freeze,
         'source.lang.swift.decl.function.free' => {
           jazzy: 'Function',
           dash: 'Function',

data/lib/jazzy/sourcekitten.rb

@@ -15,17 +15,49 @@ module Jazzy
     @documented_count = 0
     @undocumented_tokens = []
 
-    # Group root-level docs by type and add as children to a group doc element
-    def self.group_docs(docs, type)
-      group, docs = docs.partition { |doc| doc.type == type }
-      docs << SourceDeclaration.new.tap do |sd|
+    # Group root-level docs by custom categories (if any) and type
+    def self.group_docs(docs)
+      custom_categories, docs = group_custom_categories(docs)
+      type_categories, uncategorized = group_type_categories(
+        docs, custom_categories.any? ? 'Other ' : '')
+      custom_categories + type_categories + uncategorized
+    end
+
+    def self.group_custom_categories(docs)
+      group = Config.instance.custom_categories.map do |category|
+        children = category['children'].flat_map do |name|
+          docs_with_name, docs = docs.partition { |doc| doc.name == name }
+          if docs_with_name.empty?
+            STDERR.puts 'WARNING: No documented top-level declarations match ' \
+                        "name \"#{name}\" specified in categories file"
+          end
+          docs_with_name
+        end
+        # Category config overrides alphabetization
+        children.each.with_index { |child, i| child.nav_order = i }
+        make_group(children, category['name'], '')
+      end
+      [group.compact, docs]
+    end
+
+    def self.group_type_categories(docs, type_category_prefix)
+      group = SourceDeclaration::Type.all.map do |type|
+        children, docs = docs.partition { |doc| doc.type == type }
+        make_group(
+          children,
+          type_category_prefix + type.plural_name,
+          "The following #{type.plural_name.downcase} are available globally.")
+      end
+      [group.compact, docs]
+    end
+
+    def self.make_group(group, name, abstract)
+      SourceDeclaration.new.tap do |sd|
         sd.type     = SourceDeclaration::Type.overview
-        sd.name     = type.plural_name
-        sd.abstract = "The following #{type.plural_name.downcase} are " \
-                      'available globally.'
+        sd.name     = name
+        sd.abstract = abstract
         sd.children = group
-      end if group.count > 0
-      docs
+      end unless group.empty?
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -33,20 +65,22 @@ module Jazzy
     # @return [Hash] input docs with URLs
     def self.make_doc_urls(docs, parents)
       docs.each do |doc|
-        if doc.children.count > 0
-          # Create HTML page for this doc if it has children
-          parents_slash = parents.count > 0 ? '/' : ''
-          doc.url = parents.join('/') + parents_slash + doc.name + '.html'
-          doc.children = make_doc_urls(doc.children, parents + [doc.name])
+        if parents.empty? || doc.children.count > 0
+          # Create HTML page for this doc if it has children or is root-level
+          doc.url = (
+              subdir_for_doc(doc, parents) +
+              [doc.name + '.html']
+            ).join('/')
+          doc.children = make_doc_urls(doc.children, parents + [doc])
         else
           # Don't create HTML page for this doc if it doesn't have children
           # Instead, make its link a hash-link on its parent's page
           if doc.typename == '<<error type>>'
             warn 'A compile error prevented ' +
-              (parents[1..-1] + [doc.name]).join('.') + ' from receiving a ' \
-              'unique USR. Documentation may be incomplete. Please check for ' \
-              'compile errors by running `xcodebuild ' \
-              "#{Config.instance.xcodebuild_arguments.shelljoin}`."
+              (parents[1..-1] + [doc]).map(&:name).join('.') +
+              ' from receiving a unique USR. Documentation may be ' \
+              'incomplete. Please check for compile errors by running ' \
+              "`xcodebuild #{Config.instance.xcodebuild_arguments.shelljoin}`."
           end
           id = doc.usr
           unless id
@@ -58,12 +92,22 @@ module Jazzy
               'project. If this token is declared in an `#if` block, please ' \
               'ignore this message.'
           end
-          doc.url = parents.join('/') + '.html#/' + id
+          doc.url = parents.last.url + '#/' + id
         end
       end
     end
     # rubocop:enable Metrics/MethodLength
 
+    # Determine the subdirectory in which a doc should be placed
+    def self.subdir_for_doc(doc, parents)
+      parents.map(&:name).tap do |names|
+        # We always want to create top-level subdirs according to type (Struct,
+        # Class, etc), but parents[0] might be a custom category name.
+        top_level_decl = (parents + [doc])[1]
+        names[0] = top_level_decl.type.plural_name if top_level_decl
+      end
+    end
+
     # Run sourcekitten with given arguments and return STDOUT
     def self.run_sourcekitten(arguments)
       xcode = XCInvoke::Xcode.find_swift_version(Config.instance.swift_version)
@@ -88,19 +132,16 @@ module Jazzy
     end
 
     def self.should_document?(doc)
-      unless doc['key.usr']
-        warn "`#{doc['key.name']}` has no USR. First make sure all modules "  \
-              'used in your project have been imported. If all used modules ' \
-              'are imported, please report this problem by filing an issue '  \
-              'at https://github.com/realm/jazzy/issues along with your '     \
-              'Xcode project. If this token is declared in an `#if` block, '  \
-              'please ignore this message.'
-        return false
-      end
       return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
 
-      # Always document extensions, since we can't tell what ACL they are
-      return true if doc['key.kind'] == 'source.lang.swift.decl.extension'
+      # Document extensions & enum elements, since we can't tell their ACL.
+      type = SourceDeclaration::Type.new(doc['key.kind'])
+      return true if type.enum_element?
+      if type.extension?
+        return Array(doc['key.substructure']).any? do |subdoc|
+          should_document?(subdoc)
+        end
+      end
 
       SourceDeclaration::AccessControlLevel.from_doc(doc) >= @min_acl
     end
@@ -153,10 +194,7 @@ module Jazzy
         doc['key.parsed_declaration'] || doc['key.doc.declaration'],
         'swift',
       )
-      stripped_comment = string_until_first_rest_definition(
-        doc['key.doc.comment'],
-      ) || ''
-      declaration.abstract = Jazzy.markdown.render(stripped_comment)
+      declaration.abstract = comment_from_doc(doc)
       declaration.discussion = ''
       declaration.return = make_paragraphs(doc, 'key.doc.result_discussion')
 
@@ -165,10 +203,15 @@ module Jazzy
       @documented_count += 1
     end
 
-    def self.string_until_first_rest_definition(string)
-      matches = /^\s*:[^\s]+:/.match(string)
-      return string unless matches
-      string[0...matches.begin(0)]
+    def self.comment_from_doc(doc)
+      swift_version = Config.instance.swift_version.to_f
+      comment = doc['key.doc.comment'] || ''
+      if swift_version < 2
+        # comment until first ReST definition
+        matches = /^\s*:[^\s]+:/.match(comment)
+        comment = comment[0...matches.begin(0)] if matches
+      end
+      Jazzy.markdown.render(comment)
     end
 
     def self.make_substructure(doc, declaration)
@@ -198,6 +241,11 @@ module Jazzy
         if declaration.type.mark? && doc['key.name'].start_with?('MARK: ')
           current_mark = SourceMark.new(doc['key.name'])
         end
+        if declaration.type.enum_case?
+          # Enum "cases" are thin wrappers around enum "elements".
+          declarations += make_source_declarations(doc['key.substructure'])
+          next
+        end
         next unless declaration.type.should_document?
 
         unless declaration.type.name
@@ -256,9 +304,10 @@ module Jazzy
       sourcekitten_json = filter_excluded_files(JSON.parse(sourcekitten_output))
       docs = make_source_declarations(sourcekitten_json)
       docs = deduplicate_declarations(docs)
-      SourceDeclaration::Type.all.each do |type|
-        docs = group_docs(docs, type)
-      end
+      docs = group_docs(docs)
+      # Remove top-level enum cases because it means they have an ACL lower
+      # than min_acl
+      docs = docs.reject { |doc| doc.type.enum_element? }
       [make_doc_urls(docs, []), doc_coverage, @undocumented_tokens]
     end
   end

data/spec/integration_spec.rb

@@ -87,24 +87,32 @@ describe_cli 'jazzy' do
     s.replace_path ROOT.to_s, 'ROOT'
   end
 
-  describe 'jazzy' do
+  travis_swift = ENV['TRAVIS_SWIFT_VERSION']
+
+  describe 'jazzy swift 1.2' do
     describe 'Creates docs with a module name, author name, project URL, ' \
       'xcodebuild options, and github info' do
-      behaves_like cli_spec 'document_alamofire',
+      behaves_like cli_spec 'document_alamofire1.2',
                             '-m Alamofire -a Alamofire ' \
                             '-u https://nshipster.com/alamofire ' \
                             '-x -project,Alamofire.xcodeproj,-dry-run ' \
                             '-g https://github.com/Alamofire/Alamofire ' \
                             '--github-file-prefix https://github.com/' \
-                            'Alamofire/Alamofire/blob/1.1.0 ' \
-                            '--module-version 1.1.0 ' \
+                            'Alamofire/Alamofire/blob/1.3.1 ' \
+                            '--module-version 1.3.1 ' \
                             '-r http://static.realm.io/jazzy_demo/Alamofire/ ' \
-                            '--skip-undocumented'
+                            '--skip-undocumented ' \
+                            '--swift-version=1.2'
     end
 
     describe 'Creates Realm Swift docs' do
-      realm_version = '0.93.2'
-      behaves_like cli_spec 'document_realm_swift',
+      realm_version = ''
+      dir = ROOT + 'spec/integration_specs/document_realm_swift1.2/before'
+      Dir.chdir(dir) do
+        realm_version = `./build.sh get-version`.chomp
+        `REALM_SWIFT_VERSION=1.2 ./build.sh set-swift-version`
+      end
+      behaves_like cli_spec 'document_realm_swift1.2',
                             '--author Realm ' \
                             '--author_url "https://realm.io" ' \
                             '--github_url ' \
@@ -116,12 +124,51 @@ describe_cli 'jazzy' do
                             '--root-url https://realm.io/docs/swift/' \
                             "#{realm_version}/api/ " \
                             '--xcodebuild-arguments ' \
-                            '-project,RealmSwift.xcodeproj,-dry-run'
+                            '-project,RealmSwift.xcodeproj,-dry-run ' \
+                            '--swift-version=1.2'
     end
 
     describe 'Creates docs for a podspec with dependencies and subspecs' do
       behaves_like cli_spec 'document_moya_podspec',
-                            '--podspec=Moya.podspec'
+                            '--podspec=Moya.podspec --swift-version=1.2'
+    end
+  end if !travis_swift || travis_swift == '1.2'
+
+  describe 'jazzy swift 2.0' do
+    describe 'Creates docs with a module name, author name, project URL, ' \
+      'xcodebuild options, and github info' do
+      behaves_like cli_spec 'document_alamofire',
+                            '-m Alamofire -a Alamofire ' \
+                            '-u https://nshipster.com/alamofire ' \
+                            '-x -project,Alamofire.xcodeproj,-dry-run ' \
+                            '-g https://github.com/Alamofire/Alamofire ' \
+                            '--github-file-prefix https://github.com/' \
+                            'Alamofire/Alamofire/blob/swift-2.0 ' \
+                            '--module-version swift-2.0 ' \
+                            '-r http://static.realm.io/jazzy_demo/Alamofire/ ' \
+                            '--skip-undocumented'
+    end
+
+    describe 'Creates Realm Swift docs' do
+      realm_version = ''
+      Dir.chdir(ROOT + 'spec/integration_specs/document_realm_swift/before') do
+        realm_version = `./build.sh get-version`.chomp
+        `REALM_SWIFT_VERSION=2.0 ./build.sh set-swift-version`
+      end
+      behaves_like cli_spec 'document_realm_swift',
+                            '--author Realm ' \
+                            '--author_url "https://realm.io" ' \
+                            '--github_url ' \
+                            'https://github.com/realm/realm-cocoa ' \
+                            '--github-file-prefix https://github.com/realm/' \
+                            "realm-cocoa/tree/v#{realm_version} " \
+                            '--module RealmSwift ' \
+                            "--module-version #{realm_version} " \
+                            '--root-url https://realm.io/docs/swift/' \
+                            "#{realm_version}/api/ " \
+                            '--xcodebuild-arguments ' \
+                            '-project,RealmSwift.xcodeproj,-dry-run ' \
+                            '--template-directory "docs/templates/swift" '
     end
 
     describe 'Creates docs for Swift project with a variety of contents' do
@@ -132,5 +179,5 @@ describe_cli 'jazzy' do
                             '-x -dry-run ' \
                             '--min-acl private'
     end
-  end
+  end if !travis_swift || travis_swift == '2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - JP Simard
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-27 00:00:00.000000000 Z
+date: 2015-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods
@@ -179,9 +179,9 @@ files:
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Commandant
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Commandant
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Resources/Info.plist
-- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/LlamaKit
-- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/LlamaKit
-- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/Resources/Info.plist
+- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Result
+- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Resources/Info.plist
+- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Result
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/SWXMLHash
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/Resources/Info.plist
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/SWXMLHash
@@ -194,7 +194,6 @@ files:
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDispatch.dylib
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftFoundation.dylib
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftObjectiveC.dylib
-- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftSecurity.dylib
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/SourceKittenFramework
 - lib/jazzy/SourceKitten/Rakefile