diff --git a/.travis.yml b/.travis.yml index c63e651ce..057f239f8 100644 --- a/.travis.yml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 653981d09..f40c63794 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,18 @@ ##### Breaking -* None. +* `--swift-version` now defaults to 2.0 instead of 1.2. + [JP Simard](https://github.com/jpsim) ##### Enhancements -* None. +* 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 @@ -14,6 +21,13 @@ [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 diff --git a/SourceKitten b/SourceKitten index 6780fbbf0..4106ae36b 160000 --- a/SourceKitten +++ b/SourceKitten @@ -1 +1 @@ -Subproject commit 6780fbbf026f1ecef50a9706cf17d7a7754e525b +Subproject commit 4106ae36b4fc7a98406ed9bdd1d64074a04a35be diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Commandant b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Commandant index b93ac9faa..74f56f87c 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Commandant and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Commandant differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Resources/Info.plist b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Resources/Info.plist index 0bed7ffaf..44a821ac9 100644 --- a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Resources/Info.plist +++ b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Resources/Info.plist @@ -3,7 +3,7 @@ BuildMachineOSBuild - 15A235d + 15A279b CFBundleDevelopmentRegion en CFBundleExecutable @@ -20,22 +20,26 @@ 1.0 CFBundleSignature ???? + CFBundleSupportedPlatforms + + MacOSX + CFBundleVersion 1 DTCompiler com.apple.compilers.llvm.clang.1_0 DTPlatformBuild - 6E35b + 7A192o DTPlatformVersion GM DTSDKBuild - 14D125 + 15A244e DTSDKName - macosx10.10 + macosx10.11 DTXcode - 0640 + 0700 DTXcodeBuild - 6E35b + 7A192o NSHumanReadableCopyright Copyright © 2014 Carthage. All rights reserved. diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/LlamaKit b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/LlamaKit deleted file mode 120000 index 21bc06a00..000000000 --- a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/LlamaKit +++ /dev/null @@ -1 +0,0 @@ -Versions/Current/LlamaKit \ No newline at end of file diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/LlamaKit b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/LlamaKit deleted file mode 100755 index 1b511bb43..000000000 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/LlamaKit and /dev/null differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Resources b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Resources similarity index 100% rename from lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Resources rename to lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Resources diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Result b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Result new file mode 120000 index 000000000..d95252cea --- /dev/null +++ b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Result @@ -0,0 +1 @@ +Versions/Current/Result \ No newline at end of file diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/Resources/Info.plist b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Resources/Info.plist similarity index 69% rename from lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/Resources/Info.plist rename to lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Resources/Info.plist index 37d7aa75f..c81b32a8d 100644 --- a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/A/Resources/Info.plist +++ b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Resources/Info.plist @@ -3,45 +3,44 @@ BuildMachineOSBuild - 15A235d + 15A279b CFBundleDevelopmentRegion en CFBundleExecutable - LlamaKit + Result CFBundleIdentifier - net.robnapier.LlamaKit + com.antitypical.Result CFBundleInfoDictionaryVersion 6.0 CFBundleName - LlamaKit + Result CFBundlePackageType FMWK CFBundleShortVersionString - 1.0 + 0.0.1 CFBundleSignature ???? + CFBundleSupportedPlatforms + + MacOSX + CFBundleVersion 1 DTCompiler com.apple.compilers.llvm.clang.1_0 DTPlatformBuild - 6E35b + 7A192o DTPlatformVersion GM DTSDKBuild - 14D125 + 15A244e DTSDKName - macosx10.10 + macosx10.11 DTXcode - 0640 + 0700 DTXcodeBuild - 6E35b + 7A192o NSHumanReadableCopyright - Copyright © 2014 Rob Napier. All rights reserved. - UIDeviceFamily - - 1 - 2 - + Copyright © 2015 Rob Rix. All rights reserved. diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Result b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Result new file mode 100755 index 000000000..03e5fd698 Binary files /dev/null and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Result differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/Current b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/Current similarity index 100% rename from lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/LlamaKit.framework/Versions/Current rename to lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/Current diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/Resources/Info.plist b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/Resources/Info.plist index a2ca78bb2..4f0c73a7c 100644 --- a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/Resources/Info.plist +++ b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/Resources/Info.plist @@ -3,7 +3,7 @@ BuildMachineOSBuild - 15A235d + 15A279b CFBundleDevelopmentRegion en CFBundleExecutable @@ -20,22 +20,26 @@ 1.0 CFBundleSignature ???? + CFBundleSupportedPlatforms + + MacOSX + CFBundleVersion 1 DTCompiler com.apple.compilers.llvm.clang.1_0 DTPlatformBuild - 6E35b + 7A192o DTPlatformVersion GM DTSDKBuild - 14D125 + 15A244e DTSDKName - macosx10.10 + macosx10.11 DTXcode - 0640 + 0700 DTXcodeBuild - 6E35b + 7A192o UIDeviceFamily 1 diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/SWXMLHash b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/SWXMLHash index aaa465d81..97aa7e4b4 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/SWXMLHash and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/SWXMLHash differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/Resources/Info.plist b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/Resources/Info.plist index 7268c4fc4..fac7fef6a 100644 --- a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/Resources/Info.plist +++ b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/Resources/Info.plist @@ -3,7 +3,7 @@ BuildMachineOSBuild - 15A235d + 15A279b CFBundleDevelopmentRegion en CFBundleExecutable @@ -20,22 +20,26 @@ 1.0.0 CFBundleSignature ???? + CFBundleSupportedPlatforms + + MacOSX + CFBundleVersion 1 DTCompiler com.apple.compilers.llvm.clang.1_0 DTPlatformBuild - 6E35b + 7A192o DTPlatformVersion GM DTSDKBuild - 14D125 + 15A244e DTSDKName - macosx10.10 + macosx10.11 DTXcode - 0640 + 0700 DTXcodeBuild - 6E35b + 7A192o NSHumanReadableCopyright Copyright © 2014 JP Simard. All rights reserved. diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/SwiftXPC b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/SwiftXPC index 24de0c025..acce7d42a 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/SwiftXPC and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SwiftXPC.framework/Versions/A/SwiftXPC differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCore.dylib b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCore.dylib index 48e0e4555..2d6f497c8 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCore.dylib and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCore.dylib differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCoreGraphics.dylib b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCoreGraphics.dylib index 4fa3cc484..98935d061 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCoreGraphics.dylib and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftCoreGraphics.dylib differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDarwin.dylib b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDarwin.dylib index 485115de2..0268094f5 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDarwin.dylib and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDarwin.dylib differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDispatch.dylib b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDispatch.dylib index 372f163dd..73f3ff9f8 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDispatch.dylib and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftDispatch.dylib differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftFoundation.dylib b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftFoundation.dylib index 9cbda3670..eb9a96232 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftFoundation.dylib and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftFoundation.dylib differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftObjectiveC.dylib b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftObjectiveC.dylib index af3da701e..6240bca07 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftObjectiveC.dylib and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftObjectiveC.dylib differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftSecurity.dylib b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftSecurity.dylib deleted file mode 100755 index d1eaa84af..000000000 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/libswiftSecurity.dylib and /dev/null differ diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist index 6e2de4451..5498939d2 100644 --- a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist +++ b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist @@ -3,7 +3,7 @@ BuildMachineOSBuild - 15A235d + 15A279b CFBundleDevelopmentRegion en CFBundleExecutable @@ -17,25 +17,29 @@ CFBundlePackageType FMWK CFBundleShortVersionString - 0.4.4 + 0.5.0 CFBundleSignature ???? + CFBundleSupportedPlatforms + + MacOSX + CFBundleVersion 1 DTCompiler com.apple.compilers.llvm.clang.1_0 DTPlatformBuild - 6E35b + 7A192o DTPlatformVersion GM DTSDKBuild - 14D125 + 15A244e DTSDKName - macosx10.10 + macosx10.11 DTXcode - 0640 + 0700 DTXcodeBuild - 6E35b + 7A192o NSHumanReadableCopyright Copyright © 2015 SourceKitten. All rights reserved. diff --git a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/SourceKittenFramework b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/SourceKittenFramework index 2bcd74902..c47defc1b 100755 Binary files a/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/SourceKittenFramework and b/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/SourceKittenFramework differ diff --git a/lib/jazzy/SourceKitten/bin/sourcekitten b/lib/jazzy/SourceKitten/bin/sourcekitten index 7434e3b9b..51e394d25 100755 Binary files a/lib/jazzy/SourceKitten/bin/sourcekitten and b/lib/jazzy/SourceKitten/bin/sourcekitten differ diff --git a/lib/jazzy/config.rb b/lib/jazzy/config.rb index e584a935e..7fa9515dd 100644 --- a/lib/jazzy/config.rb +++ b/lib/jazzy/config.rb @@ -30,6 +30,7 @@ class Config 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 @@ def initialize 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 @@ def self.parse! 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 @@ def self.parse! 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 diff --git a/lib/jazzy/doc.rb b/lib/jazzy/doc.rb index b82f617bf..7049254a9 100755 --- a/lib/jazzy/doc.rb +++ b/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 || ( diff --git a/lib/jazzy/doc_builder.rb b/lib/jazzy/doc_builder.rb index bfa01239f..0bed3079b 100644 --- a/lib/jazzy/doc_builder.rb +++ b/lib/jazzy/doc_builder.rb @@ -31,9 +31,12 @@ def self.doc_structure_for_docs(docs) 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 @@ def self.build(options) # @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,6 +187,8 @@ def self.document_index(source_module, path_to_root) doc[:structure] = source_module.doc_structure doc[:module_name] = source_module.name doc[:author_name] = source_module.author_name + # 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 @@ -287,6 +293,8 @@ def self.document(source_module, doc_model, path_to_root) doc[:tasks] = render_tasks(source_module, doc_model.children) doc[:module_name] = source_module.name doc[:author_name] = source_module.author_name + # 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 diff --git a/lib/jazzy/jazzy_markdown.rb b/lib/jazzy/jazzy_markdown.rb index 57f567626..913e1e938 100755 --- a/lib/jazzy/jazzy_markdown.rb +++ b/lib/jazzy/jazzy_markdown.rb @@ -19,6 +19,59 @@ def header(text, header_level) "#{text}\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 + (

\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 = '

  • ' + str << text.strip + str << "
    • \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 ? "
      \n" : "
        \n") + str << text + str << (list_type == :ordered ? "
    \n" : "\n") + end + OPTIONS = { autolink: true, fenced_code_blocks: true, diff --git a/lib/jazzy/source_declaration.rb b/lib/jazzy/source_declaration.rb index 6bbc138a1..2ee79402b 100644 --- a/lib/jazzy/source_declaration.rb +++ b/lib/jazzy/source_declaration.rb @@ -23,6 +23,7 @@ class SourceDeclaration attr_accessor :access_control_level attr_accessor :start_line attr_accessor :end_line + attr_accessor :nav_order def overview "#{abstract}\n\n#{discussion}".strip diff --git a/lib/jazzy/source_declaration/type.rb b/lib/jazzy/source_declaration/type.rb index f0ad7c680..45941afe9 100644 --- a/lib/jazzy/source_declaration/type.rb +++ b/lib/jazzy/source_declaration/type.rb @@ -31,6 +31,14 @@ def mark? 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 @@ def declaration? 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 @@ def ==(other) 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 @@ def ==(other) 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', diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb index 305ecaa3f..f443c5870 100644 --- a/lib/jazzy/sourcekitten.rb +++ b/lib/jazzy/sourcekitten.rb @@ -15,17 +15,49 @@ module SourceKitten @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 @@ def self.group_docs(docs, type) # @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 == '<>' 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 @@ def self.make_doc_urls(docs, parents) '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 @@ def self.documented_child?(doc) 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 @@ def self.make_doc_info(doc, declaration) 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 @@ def self.make_doc_info(doc, declaration) @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 @@ def self.make_source_declarations(docs) 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 @@ def self.parse(sourcekitten_output, min_acl, skip_undocumented) 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 diff --git a/spec/integration_spec.rb b/spec/integration_spec.rb index 940886112..206addf8d 100644 --- a/spec/integration_spec.rb +++ b/spec/integration_spec.rb @@ -87,24 +87,32 @@ 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 @@ '--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 @@ '-x -dry-run ' \ '--min-acl private' end - end + end if !travis_swift || travis_swift == '2.0' end diff --git a/spec/integration_specs b/spec/integration_specs index 9ac0a8a32..68a34fb6a 160000 --- a/spec/integration_specs +++ b/spec/integration_specs @@ -1 +1 @@ -Subproject commit 9ac0a8a32644662eff8d019fe1306d6259436021 +Subproject commit 68a34fb6a3c21262d31d6f97bf8466236106fe82