jazzy 0.6.2 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ae94356306e611e8d528016fb64e8552f375e512
-  data.tar.gz: a74aa7abbe93d6c123f6a12636fe05a4a82eb774
+  metadata.gz: b011225bb2035eea33feeb28e4380677670fc690
+  data.tar.gz: 2f8a49403fd26b3e0d14508046395e63bde5720c
 SHA512:
-  metadata.gz: 89643d290acf1f0e171f947d3c93ba604de3dbb55b4e37c326f2f73766f1c0d07714ecb9e20d76cfd7b189834e2253b8e916c34bb8bb73b0151d63caa4f3abee
-  data.tar.gz: d4266e1d6839e14abfcaf82932604243aa596dddef23de3b83082887ed2fc1d6f29dfbd5123842743c6ce56c30b07ed812e02af2b58b9f9f3f579da1227a733f
+  metadata.gz: 61f1e5776b51822988882f207f74ea08f28d5be662ffe2189567a2221c7b92fb76b32c682d8fbf0a06a03838caaf6f9002488051e3eb919b8a4b63c076a4261f
+  data.tar.gz: 2ce8c0525ffe80a1640e0fe2bf35c0a2c7ba7791de8f5a7a672f77916d2a3c96e5107a69b41b15177408e55a66bda6e213c1e9a19eaa9a5b4f332f644466085e

data/.gitignore

@@ -57,3 +57,4 @@ Icon
 Network Trash Folder
 Temporary Items
 .apdisk
+vendor

data/.gitmodules

@@ -3,4 +3,4 @@
 	url = https://github.com/jpsim/SourceKitten.git
 [submodule "spec/integration_specs"]
 	path = spec/integration_specs
-	url = https://github.com/Realm/jazzy-integration-specs.git
+	url = https://github.com/realm/jazzy-integration-specs.git

data/.travis.yml

@@ -5,7 +5,9 @@ branches:
 git:
   submodules: false
 before_install: git submodule update --init --recursive
-script: bundle exec rake spec
+script: 
+  - bundle exec rake spec
+  - bundle exec danger || true
 notifications:
   email: false
   slack: realmio:vPdpsG9NLDo2DNlbqtcMAQuE

data/CHANGELOG.md

@@ -1,3 +1,51 @@
+## 0.6.3
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* `--exclude` flag now supports excluding directories in addition to files.  
+  [Gurrinder](https://github.com/gurrinder)
+  [#503](https://github.com/realm/jazzy/issues/503)
+
+* The `cocoapods` gem was updated to 1.0.1 and `rouge` to 1.11.0.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [#568](https://github.com/realm/jazzy/issues/568)
+
+* Extra markdown documentation can now be included as their own pages in the
+  sidebar using the `--documentation` option and in the generated Dash docset
+  as Guides.  
+  [Karl Bowden](https://github.com/agentk)
+  [#435](https://github.com/realm/jazzy/issues/435)
+
+* Section headings can now include additional markdown content using the
+  `--abstract` option.  
+  [Karl Bowden](https://github.com/agentk)
+  [#435](https://github.com/realm/jazzy/issues/435)
+
+* If Swift version is not specified, look for Swift toolchain or clang location
+  in the following order:
+
+    * `$XCODE_DEFAULT_TOOLCHAIN_OVERRIDE`
+    * `$TOOLCHAIN_DIR`
+    * `xcrun -find swift`
+    * `/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`
+    * `/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`
+    * `~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`
+    * `~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`
+
+  This will be especially useful once jazzy supports generating docs for
+  Swift Package Manager modules with a toolchain not tied to an Xcode release.  
+  [JP Simard](https://github.com/jpsim)
+
+##### Bug Fixes
+
+* Don't document clang-unexposed Objective-C declarations.  
+  [JP Simard](https://github.com/jpsim)
+  [#573](https://github.com/realm/jazzy/issues/573)
+
 ## 0.6.2
 
 ##### Breaking
@@ -26,6 +74,7 @@
 * Objective-C documentation now also includes Swift declarations.  
   [JP Simard](https://github.com/jpsim)
   [#136](https://github.com/realm/jazzy/issues/136)
+
 * Default to the Xcode version selected in `xcode-select` if no Swift version is
   specified.  
   [Samuel Giddins](https://github.com/segiddins)
@@ -36,9 +85,11 @@
 * Uses GitHub-Flavored Markdown syntax for anchors when rendering README pages.  
   [Zachary Waldowski](https://github.com/zwaldowski)
   [#524](https://github.com/realm/jazzy/issues/524)
+
 * Fix crash when using unexposed declarations in Objective-C.  
   [JP Simard](https://github.com/jpsim)
   [#543](https://github.com/realm/jazzy/issues/543)
+
 * No longer document Swift extensions on types with an ACL lower than `min-acl`
   when they contain `MARK`s.  
   [JP Simard](https://github.com/jpsim)
@@ -54,10 +105,12 @@
   a complete list of changed options. As always, you can get a list of all
   options with `jazzy --help config`.  
   [Paul Cantrell](https://github.com/pcantrell)
+
 * Jazzy's undocumented.txt has been replaced with undocumented.json. This new
   format includes contextual information that one might use to lint
   documentation in an automated fashion.  
   [Jeff Verkoeyen](https://github.com/jverkoey)
+
 * `--swift-version` now defaults to 2.2 instead of 2.1.1.  
   [Tamar Nachmany](https://github.com/tamarnachmany)
 
@@ -66,10 +119,12 @@
 * Add `--skip-documentation` flag. Skips site generation phase. `undocumented.json`
   is still generated.  
   [Jeff Verkoeyen](https://github.com/jverkoey)
+
 * Merge Objective-C categories into their parent type documentation to match
   Swift behavior.  
   [Esad Hajdarevic](https://github.com/esad)
   [#457](https://github.com/realm/jazzy/issues/457)
+
 * Add support for documenting Swift 2.2 `associatedtype`s and infix, postfix &
   prefix operators.  
   [JP Simard](https://github.com/jpsim)

data/Dangerfile

@@ -0,0 +1,28 @@
+# Warn when there is a big PR
+warn("Big PR") if lines_of_code > 500
+
+# Don't let testing shortcuts get into master by accident
+(modified_files + added_files - %w(Dangerfile)).each do |file|
+  next unless File.file?(file)
+  contents = File.read(file)
+  if file.start_with?('spec')
+    fail("`xit` or `fit` left in tests (#{file})") if contents =~ /^\w*[xf]it/
+    fail("`fdescribe` left in tests (#{file})") if contents =~ /^\w*fdescribe/
+  end
+end
+
+# Sometimes its a README fix, or something like that - which isn't relevant for
+# including in a CHANGELOG for example
+has_app_changes = !modified_files.grep(/lib/).empty?
+has_test_changes = !modified_files.grep(/spec/).empty?
+
+# Add a CHANGELOG entry for app changes
+if !modified_files.include?("CHANGELOG.md") && has_app_changes
+  fail("Please include a CHANGELOG entry. \nYou can find it at [CHANGELOG.md](https://github.com/realm/jazzy/blob/master/CHANGELOG.md).")
+  message "Note, we hard-wrap at 80 chars and use 2 spaces after the last line."
+end
+
+# Non-trivial amounts of app changes without tests
+if lines_of_code > 50 && has_app_changes && !has_test_changes
+    warn "This PR may need tests."    
+end

data/Gemfile

@@ -16,4 +16,7 @@ group :development do
   # Integration tests
   gem 'diffy'
   gem 'clintegracon'
+  
+  # Code Review
+  gem 'danger'
 end

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    jazzy (0.6.2)
-      cocoapods (~> 0.39)
+    jazzy (0.6.3)
+      cocoapods (~> 1.0)
       mustache (~> 0.99)
       open4
       redcarpet (~> 3.2)
@@ -23,58 +23,76 @@ GEM
     addressable (2.4.0)
     ast (2.2.0)
     bacon (1.2.0)
-    claide (0.9.1)
+    claide (1.0.0)
     clintegracon (0.7.0)
       colored (~> 1.2)
       diffy
-    cocoapods (0.39.0)
+    cocoapods (1.0.1)
       activesupport (>= 4.0.2)
-      claide (~> 0.9.1)
-      cocoapods-core (= 0.39.0)
-      cocoapods-downloader (~> 0.9.3)
-      cocoapods-plugins (~> 0.4.2)
-      cocoapods-search (~> 0.1.0)
-      cocoapods-stats (~> 0.6.2)
-      cocoapods-trunk (~> 0.6.4)
-      cocoapods-try (~> 0.5.1)
+      claide (>= 1.0.0, < 2.0)
+      cocoapods-core (= 1.0.1)
+      cocoapods-deintegrate (>= 1.0.0, < 2.0)
+      cocoapods-downloader (>= 1.0.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.0.0, < 2.0)
+      cocoapods-try (>= 1.0.0, < 2.0)
       colored (~> 1.2)
       escape (~> 0.0.4)
-      molinillo (~> 0.4.0)
+      fourflusher (~> 0.3.0)
+      molinillo (~> 0.4.5)
       nap (~> 1.0)
-      xcodeproj (~> 0.28.2)
-    cocoapods-core (0.39.0)
+      xcodeproj (>= 1.1.0, < 2.0)
+    cocoapods-core (1.0.1)
       activesupport (>= 4.0.2)
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
-    cocoapods-downloader (0.9.3)
-    cocoapods-plugins (0.4.2)
+    cocoapods-deintegrate (1.0.0)
+    cocoapods-downloader (1.0.0)
+    cocoapods-plugins (1.0.0)
       nap
-    cocoapods-search (0.1.0)
-    cocoapods-stats (0.6.2)
-    cocoapods-trunk (0.6.4)
+    cocoapods-search (1.0.0)
+    cocoapods-stats (1.0.0)
+    cocoapods-trunk (1.0.0)
       nap (>= 0.8, < 2.0)
       netrc (= 0.7.8)
-    cocoapods-try (0.5.1)
+    cocoapods-try (1.0.0)
     colored (1.2)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
+    danger (0.8.1)
+      claide
+      colored (~> 1.2)
+      faraday
+      git
+      octokit (~> 4.2)
+      redcarpet (~> 3.3)
+      terminal-table (~> 1)
     diffy (3.1.0)
     escape (0.0.4)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    fourflusher (0.3.1)
     fuzzy_match (2.0.4)
+    git (1.3.0)
     hashdiff (0.3.0)
     i18n (0.7.0)
     json (1.8.3)
     liferaft (0.0.4)
     metaclass (0.0.4)
-    minitest (5.8.4)
+    minitest (5.9.0)
     mocha (1.1.0)
       metaclass (~> 0.0.1)
     mocha-on-bacon (0.2.2)
       mocha (>= 0.13.0)
     molinillo (0.4.5)
+    multipart-post (2.0.0)
     mustache (0.99.8)
     nap (1.1.0)
     netrc (0.7.8)
+    octokit (4.3.0)
+      sawyer (~> 0.7.0, >= 0.5.3)
     open4 (1.3.4)
     parser (2.3.0.7)
       ast (~> 2.2)
@@ -84,7 +102,7 @@ GEM
     rainbow (2.1.0)
     rake (10.5.0)
     redcarpet (3.3.4)
-    rouge (1.10.1)
+    rouge (1.11.0)
     rubocop (0.39.0)
       parser (>= 2.3.0.7, < 3.0)
       powerpack (~> 0.1)
@@ -94,7 +112,11 @@ GEM
     ruby-progressbar (1.7.5)
     safe_yaml (1.0.4)
     sass (3.4.22)
+    sawyer (0.7.0)
+      addressable (>= 2.3.5, < 2.5)
+      faraday (~> 0.8, < 0.10)
     sqlite3 (1.3.11)
+    terminal-table (1.5.2)
     thread_safe (0.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
@@ -105,9 +127,9 @@ GEM
       hashdiff
     xcinvoke (0.2.1)
       liferaft (~> 0.0.4)
-    xcodeproj (0.28.2)
+    xcodeproj (1.1.0)
       activesupport (>= 3)
-      claide (~> 0.9.1)
+      claide (>= 1.0.0, < 2.0)
       colored (~> 1.2)
 
 PLATFORMS
@@ -117,6 +139,7 @@ DEPENDENCIES
   bacon
   bundler (~> 1.7)
   clintegracon
+  danger
   diffy
   jazzy!
   mocha
@@ -127,4 +150,4 @@ DEPENDENCIES
   webmock
 
 BUNDLED WITH
-   1.11.2
+   1.12.5

data/README.md

@@ -19,6 +19,10 @@ of Apple’s official reference documentation, post WWDC 2014.
 
 ![Screenshot](screenshot.jpg)
 
+This project adheres to the [Contributor Covenant Code of Conduct](https://realm.io/conduct).
+By participating, you are expected to uphold this code. Please report
+unacceptable behavior to [info@realm.io](mailto:info@realm.io).
+
 ## Requirements
 
 * A version of [Xcode][xcode] (6.x or 7.x) capable of building the project 
@@ -132,6 +136,40 @@ 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
 directory.
 
+### Guides
+
+| Description | Command |
+| ---         | ---     |
+| Command line option | `--documentation={file pattern}` |
+| Example             | `--documentation=Docs/*.md` |
+| jazzy.yaml example  | `documentation: Docs/*.md` |
+
+Using the `--documentation` option, extra markdown files can be integrated into the generated docs and sidebar navigation.
+
+Any files found matching the file pattern will be parsed and included as a document with the type 'Guide' when generated. If the files are not included using the `custom_categories` config option, they will be grouped under 'Other Guides' in the sidebar navigation.
+
+There are a few limitations:
+- File names must be unique from source files.
+- Readme should be specified separately using the `readme_path` option.
+
+### Section description abstracts
+
+| Description | Command |
+| ---         | ---     |
+| Command line option | `--abstract={file pattern}` |
+| Example             | `--abstract=Docs/Sections/*.md` |
+| jazzy.yaml example  | `abstract: Docs/Sections/*.md` |
+
+Using the `--abstract` options, extra markdown can be included after the heading of section overview pages. Think of it as a template include.
+
+The list of files matching the pattern is compared against the list of sections generated and if a match is found, it's contents will be included in that section before listing source output.
+
+Unlike the `--documentation` option, these files are not included in navigation and if a file does not match a section title, it is not included at all.
+
+This is very helpful when using `custom_categories` for grouping types and including relevant documentation in those sections.
+
+For an example of a project using both `--documentation` and `--abstract` see: [http://reswift.github.io/ReSwift/](http://reswift.github.io/ReSwift/)
+
 ## Troubleshooting
 
 #### Swift
@@ -173,6 +211,18 @@ Instructions to build SourceKitten from source can be found at
 
 This project is released under the [MIT license](https://github.com/realm/jazzy/blob/master/LICENSE).
 
+## About
+
+<img src="realm.png" width="184" />
+
+Jazzy is maintained and funded by Realm Inc. The names and logos for
+Realm are trademarks of Realm Inc.
+
+We :heart: open source software!
+See [our other open source projects](https://github.com/realm),
+read [our blog](https://realm.io/news) or say hi on twitter
+([@realm](https://twitter.com/realm)).
+
 [clang]: http://clang.llvm.org "Clang"
 [sourcekit]: http://www.jpsim.com/uncovering-sourcekit "Uncovering SourceKit"
 [ast]: http://clang.llvm.org/docs/IntroductionToTheClangAST.html "Introduction To The Clang AST"

data/jazzy.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
 
   spec.extensions    = ['lib/jazzy/SourceKitten/Rakefile']
 
-  spec.add_runtime_dependency 'cocoapods', '~> 0.39'
+  spec.add_runtime_dependency 'cocoapods', '~> 1.0'
   spec.add_runtime_dependency 'mustache', '~> 0.99'
   spec.add_runtime_dependency 'open4'
   spec.add_runtime_dependency 'redcarpet', '~> 3.2'

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>15F34</string>
+	<string>15G7a</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>

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

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>15F34</string>
+	<string>15G7a</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>

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>15F34</string>
+	<string>15G7a</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>

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

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>BuildMachineOSBuild</key>
+	<string>15G7a</string>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en</string>
+	<key>CFBundleExecutable</key>
+	<string>Yaml</string>
+	<key>CFBundleIdentifier</key>
+	<string>behrang.Yaml</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>Yaml</string>
+	<key>CFBundlePackageType</key>
+	<string>FMWK</string>
+	<key>CFBundleShortVersionString</key>
+	<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>7D1014</string>
+	<key>DTPlatformVersion</key>
+	<string>GM</string>
+	<key>DTSDKBuild</key>
+	<string>15E60</string>
+	<key>DTSDKName</key>
+	<string>macosx10.11</string>
+	<key>DTXcode</key>
+	<string>0731</string>
+	<key>DTXcodeBuild</key>
+	<string>7D1014</string>
+</dict>
+</plist>

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>15F34</string>
+	<string>15G7a</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.12.2</string>
+	<string>0.13.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleSupportedPlatforms</key>

data/lib/jazzy/config.rb

@@ -150,8 +150,8 @@ module Jazzy
       parse: ->(sd) { expand_path(sd) }
 
     config_attr :excluded_files,
-      command_line: ['-e', '--exclude file1,file2,…fileN', Array],
-      description: 'Files to be excluded from documentation',
+      command_line: ['-e', '--exclude file1,file2,directory3,…fileN', Array],
+      description: 'Files/directories to be excluded from documentation',
       default: [],
       parse: ->(files) do
         Array(files).map { |f| expand_path(f) }
@@ -197,6 +197,16 @@ module Jazzy
       description: 'The path to a markdown README file',
       parse: ->(rp) { expand_path(rp) }
 
+    config_attr :documentation_glob,
+      command_line: '--documentation GLOB',
+      description: 'Glob that matches available documentation',
+      parse: ->(dg) { Pathname.glob(dg) }
+
+    config_attr :abstract_glob,
+      command_line: '--abstract GLOB',
+      description: 'Glob that matches available abstracts for categories',
+      parse: ->(ag) { Pathname.glob(ag) }
+
     config_attr :podspec,
       command_line: '--podspec FILEPATH',
       parse: ->(ps) { PodspecDocumenter.create_podspec(Pathname(ps)) if ps },

data/lib/jazzy/doc_builder.rb

@@ -7,10 +7,12 @@ require 'sass'
 require 'jazzy/config'
 require 'jazzy/doc'
 require 'jazzy/docset_builder'
+require 'jazzy/documentation_generator'
 require 'jazzy/jazzy_markdown'
 require 'jazzy/podspec_documenter'
 require 'jazzy/readme_generator'
 require 'jazzy/source_declaration'
+require 'jazzy/source_document'
 require 'jazzy/source_module'
 require 'jazzy/sourcekitten'
 
@@ -91,7 +93,7 @@ module Jazzy
 
     def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
-        next if doc.name != 'index' && doc.children.count == 0
+        next unless doc.render?
         # Assuming URL is relative to documentation root:
         path = output_dir + (doc.url || "#{doc.name}.html")
         block.call(doc, path)
@@ -109,9 +111,11 @@ module Jazzy
 
       structure = doc_structure_for_docs(docs)
 
-      docs << SourceDeclaration.new.tap do |sd|
+      docs << SourceDocument.new.tap do |sd|
         sd.name = 'index'
         sd.children = []
+        sd.type = SourceDeclaration::Type.new 'document.markdown'
+        sd.readme_path = options.readme_path
       end
 
       source_module = SourceModule.new(options, docs, structure, coverage)
@@ -138,7 +142,7 @@ module Jazzy
         sourcekitten_output,
         options.min_acl,
         options.skip_undocumented,
-      )
+        DocumentationGenerator.source_docs)
 
       prepare_output_dir(options.output, options.clean)
       write_lint_report(undocumented, options)
@@ -238,15 +242,17 @@ module Jazzy
       end
     end
 
-    # Build index Mustache document
+    # Build Mustache document from a markdown source file
     # @param [Config] options Build options
+    # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
     # @param [String] path_to_root
     # @param [Array] doc_structure doc structure comprised of section names and
     #        child names and URLs. @see doc_structure_for_docs
-    def self.document_index(source_module, path_to_root)
+    def self.document_markdown(source_module, doc_model, path_to_root)
       doc = Doc.new # Mustache model instance
-      doc[:name] = source_module.name
-      doc[:overview] = ReadmeGenerator.generate(source_module)
+      name = doc_model.name == 'index' ? source_module.name : doc_model.name
+      doc[:name] = name
+      doc[:overview] = Jazzy.markdown.render(doc_model.content(source_module))
       doc[:custom_head] = Config.instance.custom_head
       doc[:doc_coverage] = source_module.doc_coverage unless
         Config.instance.hide_documentation_coverage
@@ -326,7 +332,7 @@ module Jazzy
     # @param [Config] options Build options
     # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
     def self.render_tasks(source_module, children)
-      marks = children.map(&:mark).uniq
+      marks = children.map(&:mark).uniq.compact
       mark_names_counts = {}
       marks.map do |mark|
         mark_children = children.select { |child| child.mark == mark }
@@ -349,8 +355,8 @@ module Jazzy
     # @param [Array] doc_structure doc structure comprised of section names and
     #        child names and URLs. @see doc_structure_for_docs
     def self.document(source_module, doc_model, path_to_root)
-      if doc_model.name == 'index'
-        return document_index(source_module, path_to_root)
+      if doc_model.type.kind == 'document.markdown'
+        return document_markdown(source_module, doc_model, path_to_root)
       end
 
       doc = Doc.new # Mustache model instance

data/lib/jazzy/documentation_generator.rb

@@ -0,0 +1,38 @@
+require 'pathname'
+
+require 'jazzy/jazzy_markdown'
+require 'jazzy/source_document'
+
+module Jazzy
+  module DocumentationGenerator
+    extend Config::Mixin
+
+    def self.source_docs
+      documentation_entries.map do |file_path|
+        SourceDocument.new.tap do |sd|
+          sd.name = File.basename(file_path, '.md')
+          sd.url = sd.name.downcase.strip
+                     .tr(' ', '-').gsub(/[^\w-]/, '') + '.html'
+          sd.type = SourceDeclaration::Type.new 'document.markdown'
+          sd.children = []
+          sd.overview = overview Pathname(file_path)
+          sd.usr = 'documentation.' + sd.name
+          sd.abstract = ''
+          sd.return = ''
+          sd.parameters = []
+        end
+      end
+    end
+
+    def self.overview(file_path)
+      return '' unless file_path && file_path.exist?
+      file_path.read
+    end
+
+    def self.documentation_entries
+      return [] unless
+        config.documentation_glob_configured && config.documentation_glob
+      config.documentation_glob.select { |e| File.file? e }
+    end
+  end
+end

data/lib/jazzy/gem_version.rb

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

data/lib/jazzy/podspec_documenter.rb

@@ -10,17 +10,25 @@ module Jazzy
     end
 
     def sourcekitten_output
-      sandbox = Pod::Sandbox.new(pod_config.sandbox_root)
-      installer = Pod::Installer.new(sandbox, podfile)
-      installer.install!
-      stdout = Dir.chdir(sandbox.root) do
-        pod_targets.map do |t|
-          SourceKitten.run_sourcekitten(
-            %W(doc --module-name #{podspec.module_name} -- -target #{t}),
-          )
+      installation_root = Pathname(Dir.mktmpdir(['jazzy', podspec.name]))
+      installation_root.rmtree if installation_root.exist?
+      Pod::Config.instance.with_changes(installation_root: installation_root) do
+        sandbox = Pod::Sandbox.new(Pod::Config.instance.sandbox_root)
+        installer = Pod::Installer.new(sandbox, podfile)
+        installer.install!
+        stdout = Dir.chdir(sandbox.root) do
+          targets = installer.pod_targets
+                             .select { |pt| pt.pod_name == podspec.root.name }
+                             .map(&:label)
+
+          targets.map do |t|
+            SourceKitten.run_sourcekitten(
+              %W(doc --module-name #{podspec.module_name} -- -target #{t}),
+            )
+          end
         end
+        stdout.reduce([]) { |a, s| a + JSON.load(s) }.to_json
       end
-      stdout.reduce([]) { |a, s| a + JSON.load(s) }.to_json
     end
 
     def self.create_podspec(podspec_path)
@@ -82,18 +90,6 @@ module Jazzy
 
     # @!group SourceKitten output helper methods
 
-    attr_reader :pod_targets
-
-    def pod_config
-      Pod::Config.instance.tap do |c|
-        c.installation_root = Pathname(Dir.mktmpdir)
-        c.installation_root.rmtree if c.installation_root.exist?
-        c.integrate_targets = false
-        c.deduplicate_targets = false
-        c.deterministic_uuids = false
-      end
-    end
-
     def pod_path
       if podspec.defined_in_file
         podspec.defined_in_file.parent
@@ -105,19 +101,18 @@ module Jazzy
     def podfile
       podspec = @podspec
       path = pod_path
-      targets = (@pod_targets ||= [])
       @podfile ||= Pod::Podfile.new do
-        platform :ios, '8.0'
+        install! 'cocoapods',
+                 integrate_targets: false,
+                 deterministic_uuids: false
+
         [podspec, *podspec.recursive_subspecs].each do |ss|
           ss.available_platforms.each do |p|
             # Travis builds take too long when building docs for all available
             # platforms for the Moya integration spec, so we just document OSX.
             # TODO: remove once jazzy is fast enough.
-            next if ENV['JAZZY_INTEGRATION_SPECS'] &&
-                    !p.to_s.start_with?('OS X')
-            t = "Jazzy-#{ss.name.gsub('/', '__')}-#{p.name}"
-            targets << "Pods-#{t}-#{ss.root.name}"
-            target(t) do
+            next if ENV['JAZZY_INTEGRATION_SPECS'] && p.name != :osx
+            target("Jazzy-#{ss.name.gsub('/', '__')}-#{p.name}") do
               use_frameworks!
               platform p.name, p.deployment_target
               pod ss.name, path: path.realpath.to_s

data/lib/jazzy/source_declaration/type.rb

@@ -88,6 +88,10 @@ module Jazzy
           kind == 'source.lang.swift.decl.var.local'
       end
 
+      def objc_unexposed?
+        kind == 'sourcekitten.source.lang.objc.decl.unexposed'
+      end
+
       def self.overview
         Type.new('Overview')
       end
@@ -102,8 +106,13 @@ module Jazzy
       end
 
       TYPES = {
-        # Objective-C
+        # Markdown
+        'document.markdown' => {
+          jazzy: 'Guide',
+          dash: 'Guide',
+        }.freeze,
 
+        # Objective-C
         'sourcekitten.source.lang.objc.decl.unexposed' => {
           jazzy: 'Unexposed',
           dash: 'Unexposed',

data/lib/jazzy/source_declaration.rb

@@ -8,6 +8,14 @@ module Jazzy
     # static type of declared element (e.g. String.Type -> ())
     attr_accessor :typename
 
+    def type?(type_kind)
+      respond_to?(:type) && type.kind == type_kind
+    end
+
+    def render?
+      type?('document.markdown') || children.count != 0
+    end
+
     # Element containing this declaration in the code
     attr_accessor :parent_in_code
 
@@ -69,7 +77,26 @@ module Jazzy
     attr_accessor :nav_order
 
     def overview
-      "#{abstract}\n\n#{discussion}".strip
+      alternative_abstract || "#{abstract}\n\n#{discussion}".strip
+    end
+
+    def alternative_abstract
+      if file = alternative_abstract_file
+        Pathname(file).read
+      end
+    end
+
+    def alternative_abstract_file
+      abstract_glob.select do |f|
+        File.basename(f).split('.').first == name
+      end.first
+    end
+
+    def abstract_glob
+      return [] unless
+        Config.instance.abstract_glob_configured &&
+        Config.instance.abstract_glob
+      Config.instance.abstract_glob.select { |e| File.file? e }
     end
   end
 end

data/lib/jazzy/source_document.rb

@@ -0,0 +1,72 @@
+require 'pathname'
+
+require 'jazzy/jazzy_markdown'
+
+module Jazzy
+  class SourceDocument < SourceDeclaration
+    attr_accessor :overview
+    attr_accessor :readme_path
+
+    def config
+      Config.instance
+    end
+
+    def url
+      name.downcase.strip.tr(' ', '-').gsub(/[^\w-]/, '') + '.html'
+    end
+
+    def content(source_module)
+      return readme_content(source_module) if name == 'index'
+      overview
+    end
+
+    def readme_content(source_module)
+      config_readme || fallback_readme || generated_readme(source_module)
+    end
+
+    def config_readme
+      readme_path.read if readme_path && readme_path.exist?
+    end
+
+    def fallback_readme
+      %w(README.md README.markdown README.mdown README).each do |potential_name|
+        file = config.source_directory + potential_name
+        return file.read if file.exist?
+      end
+      false
+    end
+
+    def generated_readme(source_module)
+      if podspec = config.podspec
+        ### License
+
+        # <a href="#{license[:url]}">#{license[:license]}</a>
+        <<-EOS
+# #{podspec.name}
+
+### #{podspec.summary}
+
+#{podspec.description}
+
+### Installation
+
+```ruby
+pod '#{podspec.name}'
+```
+
+### Authors
+
+#{source_module.author_name}
+EOS
+      else
+        <<-EOS
+# #{source_module.name}
+
+### Authors
+
+#{source_module.author_name}
+EOS
+      end
+    end
+  end
+end

data/lib/jazzy/source_module.rb

@@ -37,7 +37,7 @@ module Jazzy
         d.map(&:children).each { |c| visitor[c] }
       end
       visitor[docs]
-      all_declarations
+      all_declarations.select { |doc| doc.name != 'index' }
     end
   end
 end

data/lib/jazzy/sourcekitten.rb

@@ -138,12 +138,12 @@ module Jazzy
         unless xcode = XCInvoke::Xcode.find_swift_version(swift_version)
           raise "Unable to find an Xcode with swift version #{swift_version}."
         end
+        env = xcode.as_env
       else
-        xcode = XCInvoke::Xcode.selected
+        env = ENV
       end
       bin_path = Pathname(__FILE__).parent + 'SourceKitten/bin/sourcekitten'
-      output, = Executable.execute_command(bin_path, arguments, true,
-                                           env: xcode.as_env)
+      output, = Executable.execute_command(bin_path, arguments, true, env: env)
       output
     end
 
@@ -413,7 +413,7 @@ module Jazzy
       excluded_files = Config.instance.excluded_files
       json.map do |doc|
         key = doc.keys.first
-        doc[key] unless excluded_files.include?(Pathname(key))
+        doc[key] unless excluded_files.detect { |f| File.fnmatch?(key, f) }
       end.compact
     end
 
@@ -479,7 +479,7 @@ module Jazzy
       end
     end
 
-    def self.reject_objc_enum_typedefs(docs)
+    def self.reject_objc_types(docs)
       enums = docs.flat_map do |doc|
         doc.children.select { |child| child.type.objc_enum? }.map(&:name)
       end
@@ -489,19 +489,20 @@ module Jazzy
         end
         doc
       end
+      docs.reject { |doc| doc.type.objc_unexposed? }
     end
 
     # Parse sourcekitten STDOUT output as JSON
     # @return [Hash] structured docs
-    def self.parse(sourcekitten_output, min_acl, skip_undocumented)
+    def self.parse(sourcekitten_output, min_acl, skip_undocumented, inject_docs)
       @min_acl = min_acl
       @skip_undocumented = skip_undocumented
       sourcekitten_json = filter_excluded_files(JSON.parse(sourcekitten_output))
-      docs = make_source_declarations(sourcekitten_json)
+      docs = make_source_declarations(sourcekitten_json).concat inject_docs
       docs = ungrouped_docs = deduplicate_declarations(docs)
       docs = group_docs(docs)
       if Config.instance.objc_mode
-        docs = reject_objc_enum_typedefs(docs)
+        docs = reject_objc_types(docs)
       else
         # Remove top-level enum cases because it means they have an ACL lower
         # than min_acl

data/spec/integration_spec.rb

@@ -49,8 +49,15 @@ require 'colored'
 require 'CLIntegracon'
 
 require 'cocoapods'
-Pod::Config.instance.silent = true
-Pod::Command::Setup.invoke
+Pod::Config.instance.with_changes(silent: true) do
+  config = Pod::Config.instance
+  # working around a bug where `pod setup --silent` isn't silent
+  if config.sources_manager.master_repo_functional?
+    Pod::Command::Repo::Update.invoke(%w(master))
+  else
+    Pod::Command::Setup.invoke
+  end
+end
 
 CLIntegracon.configure do |c|
   c.spec_path = ROOT + 'spec/integration_specs'
@@ -156,8 +163,8 @@ describe_cli 'jazzy' do
                             '-x -project,Alamofire.xcodeproj,-dry-run ' \
                             '-g https://github.com/Alamofire/Alamofire ' \
                             '--github-file-prefix https://github.com/' \
-                            'Alamofire/Alamofire/blob/3.1.1 ' \
-                            '--module-version 3.1.1 ' \
+                            'Alamofire/Alamofire/blob/3.4.0 ' \
+                            '--module-version 3.4.0 ' \
                             '-r http://static.realm.io/jazzy_demo/Alamofire/ ' \
                             '--skip-undocumented'
     end
@@ -189,8 +196,7 @@ describe_cli 'jazzy' do
     end
 
     describe 'Creates docs for Swift project with a variety of contents' do
-      behaves_like cli_spec 'misc_jazzy_features',
-                            '-x -dry-run --theme fullwidth'
+      behaves_like cli_spec 'misc_jazzy_features'
     end
   end if !travis_swift || travis_swift == '2.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.3
 platform: ruby
 authors:
 - JP Simard
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-21 00:00:00.000000000 Z
+date: 2016-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods
@@ -18,14 +18,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.39'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.39'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: mustache
   requirement: !ruby/object:Gem::Requirement
@@ -168,6 +168,7 @@ files:
 - ".travis.yml"
 - CHANGELOG.md
 - CONTRIBUTING.md
+- Dangerfile
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -186,6 +187,9 @@ files:
 - 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
+- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yaml.framework/Versions/A/Resources/Info.plist
+- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yaml.framework/Versions/A/Yaml
+- lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yaml.framework/Yaml
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCore.dylib
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCoreGraphics.dylib
 - lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDarwin.dylib
@@ -202,6 +206,7 @@ files:
 - lib/jazzy/doc_builder.rb
 - lib/jazzy/docset_builder.rb
 - lib/jazzy/docset_builder/info_plist.mustache
+- lib/jazzy/documentation_generator.rb
 - lib/jazzy/executable.rb
 - lib/jazzy/gem_version.rb
 - lib/jazzy/highlighter.rb
@@ -211,6 +216,7 @@ files:
 - lib/jazzy/source_declaration.rb
 - lib/jazzy/source_declaration/access_control_level.rb
 - lib/jazzy/source_declaration/type.rb
+- lib/jazzy/source_document.rb
 - lib/jazzy/source_mark.rb
 - lib/jazzy/source_module.rb
 - lib/jazzy/sourcekitten.rb
@@ -244,6 +250,7 @@ files:
 - lib/jazzy/themes/fullwidth/templates/tasks.mustache
 - logo.jpg
 - logo.sketch
+- realm.png
 - screenshot.jpg
 - spec/integration_spec.rb
 - spec/sourcekitten_spec.rb