jazzy 0.13.4 → 0.14.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/Tests.yml +52 -0
- data/.rubocop.yml +123 -24
- data/CHANGELOG.md +103 -0
- data/CONTRIBUTING.md +5 -5
- data/Dangerfile +11 -8
- data/Gemfile +3 -1
- data/Gemfile.lock +91 -69
- data/README.md +85 -13
- data/Rakefile +19 -13
- data/bin/jazzy +3 -2
- data/bin/sourcekitten +0 -0
- data/jazzy.gemspec +8 -6
- data/js/package-lock.json +30 -25
- data/js/package.json +3 -3
- data/lib/jazzy.rb +2 -0
- data/lib/jazzy/config.rb +124 -70
- data/lib/jazzy/doc.rb +3 -1
- data/lib/jazzy/doc_builder.rb +75 -81
- data/lib/jazzy/docset_builder.rb +3 -1
- data/lib/jazzy/documentation_generator.rb +6 -2
- data/lib/jazzy/executable.rb +3 -0
- data/lib/jazzy/extensions/bitbucket/img/bitbucket.svg +11 -0
- data/lib/jazzy/{themes/apple/assets → extensions/github}/img/gh.png +0 -0
- data/lib/jazzy/extensions/gitlab/img/gitlab.svg +23 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/katex.min.css +1 -1
- data/lib/jazzy/extensions/katex/js/katex.min.js +1 -1
- data/lib/jazzy/gem_version.rb +3 -1
- data/lib/jazzy/highlighter.rb +5 -3
- data/lib/jazzy/jazzy_markdown.rb +101 -30
- data/lib/jazzy/podspec_documenter.rb +14 -16
- data/lib/jazzy/search_builder.rb +4 -3
- data/lib/jazzy/source_declaration.rb +24 -5
- data/lib/jazzy/source_declaration/access_control_level.rb +7 -5
- data/lib/jazzy/source_declaration/type.rb +33 -1
- data/lib/jazzy/source_document.rb +8 -5
- data/lib/jazzy/source_host.rb +111 -0
- data/lib/jazzy/source_mark.rb +8 -6
- data/lib/jazzy/source_module.rb +6 -6
- data/lib/jazzy/sourcekitten.rb +105 -79
- data/lib/jazzy/stats.rb +4 -2
- data/lib/jazzy/symbol_graph.rb +95 -0
- data/lib/jazzy/symbol_graph/constraint.rb +98 -0
- data/lib/jazzy/symbol_graph/ext_node.rb +116 -0
- data/lib/jazzy/symbol_graph/graph.rb +195 -0
- data/lib/jazzy/symbol_graph/relationship.rb +42 -0
- data/lib/jazzy/symbol_graph/sym_node.rb +163 -0
- data/lib/jazzy/symbol_graph/symbol.rb +222 -0
- data/lib/jazzy/themes/apple/assets/css/highlight.css.scss +63 -59
- data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss +101 -4
- data/lib/jazzy/themes/apple/assets/img/spinner.gif +0 -0
- data/lib/jazzy/themes/apple/assets/js/jazzy.js +4 -0
- data/lib/jazzy/themes/apple/assets/js/jazzy.search.js +74 -0
- data/lib/jazzy/themes/apple/assets/js/jquery.min.js +2 -2
- data/lib/jazzy/themes/apple/assets/js/lunr.min.js +6 -0
- data/lib/jazzy/themes/apple/assets/js/typeahead.jquery.js +1694 -0
- data/lib/jazzy/themes/apple/templates/doc.mustache +35 -0
- data/lib/jazzy/themes/apple/templates/footer.mustache +1 -1
- data/lib/jazzy/themes/apple/templates/header.mustache +10 -3
- data/lib/jazzy/themes/apple/templates/task.mustache +4 -4
- data/lib/jazzy/themes/fullwidth/assets/css/highlight.css.scss +63 -59
- data/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss +11 -2
- data/lib/jazzy/themes/fullwidth/assets/js/jazzy.js +4 -0
- data/lib/jazzy/themes/fullwidth/assets/js/jazzy.search.js +4 -0
- data/lib/jazzy/themes/fullwidth/assets/js/jquery.min.js +2 -2
- data/lib/jazzy/themes/fullwidth/assets/js/lunr.min.js +3 -3
- data/lib/jazzy/themes/fullwidth/templates/doc.mustache +30 -0
- data/lib/jazzy/themes/fullwidth/templates/footer.mustache +1 -1
- data/lib/jazzy/themes/fullwidth/templates/header.mustache +5 -5
- data/lib/jazzy/themes/fullwidth/templates/task.mustache +4 -4
- data/lib/jazzy/themes/jony/assets/css/highlight.css.scss +63 -59
- data/lib/jazzy/themes/jony/assets/css/jazzy.css.scss +34 -2
- data/lib/jazzy/themes/jony/assets/js/jazzy.js +4 -0
- data/lib/jazzy/themes/jony/assets/js/jquery.min.js +2 -2
- data/lib/jazzy/themes/jony/templates/doc.mustache +30 -0
- data/lib/jazzy/themes/jony/templates/footer.mustache +1 -1
- data/lib/jazzy/themes/jony/templates/header.mustache +5 -5
- data/lib/jazzy/themes/jony/templates/task.mustache +4 -4
- data/spec/integration_spec.rb +54 -42
- data/spec/spec_helper.rb +3 -1
- data/spec/spec_helper/pre_flight.rb +2 -0
- metadata +43 -19
- data/.circleci/config.yml +0 -83
- data/lib/jazzy/themes/fullwidth/assets/img/gh.png +0 -0
- data/lib/jazzy/themes/jony/assets/img/gh.png +0 -0
- data/spec/sourcekitten_spec.rb +0 -6
data/Rakefile
CHANGED
@@ -1,3 +1,5 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
1
3
|
#-- Bootstrap --------------------------------------------------------------#
|
2
4
|
|
3
5
|
desc 'Initializes your working copy to run the specs'
|
@@ -9,7 +11,7 @@ task :bootstrap do
|
|
9
11
|
title 'Updating submodules'
|
10
12
|
sh 'git submodule update --init --recursive'
|
11
13
|
else
|
12
|
-
|
14
|
+
warn "\033[0;31m" \
|
13
15
|
"[!] Please install the bundler gem manually:\n" \
|
14
16
|
' $ [sudo] gem install bundler' \
|
15
17
|
"\e[0m"
|
@@ -95,7 +97,7 @@ begin
|
|
95
97
|
|
96
98
|
desc 'Runs RuboCop linter on Ruby files'
|
97
99
|
task :rubocop do
|
98
|
-
sh 'bundle exec rubocop
|
100
|
+
sh 'bundle exec rubocop'
|
99
101
|
end
|
100
102
|
|
101
103
|
#-- SourceKitten -----------------------------------------------------------#
|
@@ -115,15 +117,20 @@ begin
|
|
115
117
|
'jquery/dist/jquery.min.js' => [
|
116
118
|
'themes/apple/assets/js',
|
117
119
|
'themes/fullwidth/assets/js',
|
118
|
-
'themes/jony/assets/js'
|
120
|
+
'themes/jony/assets/js',
|
121
|
+
],
|
122
|
+
'lunr/lunr.min.js' => [
|
123
|
+
'themes/apple/assets/js',
|
124
|
+
'themes/fullwidth/assets/js',
|
125
|
+
],
|
126
|
+
'corejs-typeahead/dist/typeahead.jquery.js' => [
|
127
|
+
'themes/apple/assets/js',
|
128
|
+
'themes/fullwidth/assets/js',
|
119
129
|
],
|
120
|
-
'lunr/lunr.min.js' => ['themes/fullwidth/assets/js'],
|
121
|
-
'corejs-typeahead/dist/typeahead.jquery.js' =>
|
122
|
-
['themes/fullwidth/assets/js'],
|
123
130
|
'katex/dist/katex.min.css' => ['extensions/katex/css'],
|
124
131
|
'katex/dist/fonts' => ['extensions/katex/css'],
|
125
|
-
'katex/dist/katex.min.js' => ['extensions/katex/js']
|
126
|
-
}
|
132
|
+
'katex/dist/katex.min.js' => ['extensions/katex/js'],
|
133
|
+
}.freeze
|
127
134
|
|
128
135
|
desc 'Copies theme dependencies (`npm update/install` by hand first)'
|
129
136
|
task :theme_deps do
|
@@ -133,15 +140,14 @@ begin
|
|
133
140
|
end
|
134
141
|
end
|
135
142
|
end
|
136
|
-
|
137
143
|
rescue LoadError, NameError => e
|
138
|
-
|
144
|
+
warn "\033[0;31m" \
|
139
145
|
'[!] Some Rake tasks haven been disabled because the environment' \
|
140
146
|
' couldn’t be loaded. Be sure to run `rake bootstrap` first.' \
|
141
147
|
"\e[0m"
|
142
|
-
|
143
|
-
|
144
|
-
|
148
|
+
warn e.message
|
149
|
+
warn e.backtrace
|
150
|
+
warn ''
|
145
151
|
end
|
146
152
|
|
147
153
|
#-- Helpers ------------------------------------------------------------------#
|
data/bin/jazzy
CHANGED
@@ -1,10 +1,11 @@
|
|
1
1
|
#!/usr/bin/env ruby
|
2
|
+
# frozen_string_literal: true
|
2
3
|
|
3
4
|
if $PROGRAM_NAME == __FILE__ && !ENV['JAZZY_NO_BUNDLER']
|
4
|
-
ENV['BUNDLE_GEMFILE'] = File.expand_path('
|
5
|
+
ENV['BUNDLE_GEMFILE'] = File.expand_path('../Gemfile', __dir__)
|
5
6
|
require 'rubygems'
|
6
7
|
require 'bundler/setup'
|
7
|
-
$LOAD_PATH.unshift File.expand_path('
|
8
|
+
$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
|
8
9
|
elsif ENV['JAZZY_NO_BUNDLER']
|
9
10
|
require 'rubygems'
|
10
11
|
gem 'jazzy'
|
data/bin/sourcekitten
CHANGED
Binary file
|
data/jazzy.gemspec
CHANGED
@@ -1,4 +1,5 @@
|
|
1
1
|
# coding: utf-8
|
2
|
+
# frozen_string_literal: true
|
2
3
|
|
3
4
|
require File.expand_path('lib/jazzy/gem_version.rb', File.dirname(__FILE__))
|
4
5
|
|
@@ -9,25 +10,26 @@ Gem::Specification.new do |spec|
|
|
9
10
|
spec.email = ['jp@jpsim.com']
|
10
11
|
spec.summary = 'Soulful docs for Swift & Objective-C.'
|
11
12
|
spec.description = 'Soulful docs for Swift & Objective-C. ' \
|
12
|
-
|
13
|
-
|
13
|
+
"Run in your Xcode project's root directory for " \
|
14
|
+
'instant HTML docs.'
|
14
15
|
spec.homepage = 'https://github.com/realm/jazzy'
|
15
16
|
spec.license = 'MIT'
|
16
17
|
|
17
18
|
spec.files = `git ls-files`.split($/)
|
18
|
-
spec.executables
|
19
|
+
spec.executables << 'jazzy'
|
19
20
|
|
20
21
|
spec.add_runtime_dependency 'cocoapods', '~> 1.5'
|
21
22
|
spec.add_runtime_dependency 'mustache', '~> 1.1'
|
22
|
-
spec.add_runtime_dependency 'open4'
|
23
|
+
spec.add_runtime_dependency 'open4', '~> 1.3'
|
23
24
|
spec.add_runtime_dependency 'redcarpet', '~> 3.4'
|
25
|
+
spec.add_runtime_dependency 'rexml', '~> 3.2'
|
24
26
|
spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
|
25
27
|
spec.add_runtime_dependency 'sassc', '~> 2.1'
|
26
28
|
spec.add_runtime_dependency 'sqlite3', '~> 1.3'
|
27
29
|
spec.add_runtime_dependency 'xcinvoke', '~> 0.3.0'
|
28
30
|
|
29
|
-
spec.add_development_dependency 'bundler', '~> 1
|
31
|
+
spec.add_development_dependency 'bundler', '~> 2.1'
|
30
32
|
spec.add_development_dependency 'rake', '~> 13.0'
|
31
33
|
|
32
|
-
spec.required_ruby_version = '>= 2.
|
34
|
+
spec.required_ruby_version = '>= 2.6.3'
|
33
35
|
end
|
data/js/package-lock.json
CHANGED
@@ -1,39 +1,44 @@
|
|
1
1
|
{
|
2
|
-
"
|
3
|
-
"version": "1.0.0",
|
4
|
-
"lockfileVersion": 1,
|
2
|
+
"lockfileVersion": 2,
|
5
3
|
"requires": true,
|
6
|
-
"
|
7
|
-
"commander": {
|
8
|
-
"version": "2.
|
9
|
-
"resolved": "https://registry.npmjs.org/commander/-/commander-2.
|
10
|
-
"integrity": "sha512-
|
4
|
+
"packages": {
|
5
|
+
"node_modules/commander": {
|
6
|
+
"version": "6.2.1",
|
7
|
+
"resolved": "https://registry.npmjs.org/commander/-/commander-6.2.1.tgz",
|
8
|
+
"integrity": "sha512-U7VdrJFnJgo4xjrHpTzu0yrHPGImdsmD95ZlgYSEajAn2JKzDhDTPG9kBTefmObL2w/ngeZnilk+OV9CG3d7UA==",
|
9
|
+
"engines": {
|
10
|
+
"node": ">= 6"
|
11
|
+
}
|
11
12
|
},
|
12
|
-
"corejs-typeahead": {
|
13
|
+
"node_modules/corejs-typeahead": {
|
13
14
|
"version": "1.3.1",
|
14
15
|
"resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.1.tgz",
|
15
16
|
"integrity": "sha512-fyNlBNWJNL6EQUnJyAunEzBzRcwR2cEHtZXBi2pndHPOJ/wpOf3wbS+/Oh+kYYS5sKowQcs0LFwMSl6Y2Xeqkw==",
|
16
|
-
"
|
17
|
+
"dependencies": {
|
17
18
|
"jquery": ">=1.11"
|
18
19
|
}
|
19
20
|
},
|
20
|
-
"jquery": {
|
21
|
-
"version": "3.
|
22
|
-
"resolved": "https://registry.npmjs.org/jquery/-/jquery-3.
|
23
|
-
"integrity": "sha512-
|
21
|
+
"node_modules/jquery": {
|
22
|
+
"version": "3.6.0",
|
23
|
+
"resolved": "https://registry.npmjs.org/jquery/-/jquery-3.6.0.tgz",
|
24
|
+
"integrity": "sha512-JVzAR/AjBvVt2BmYhxRCSYysDsPcssdmTFnzyLEts9qNwmjmu4JTAMYubEfwVOSwpQ1I1sKKFcxhZCI2buerfw=="
|
24
25
|
},
|
25
|
-
"katex": {
|
26
|
-
"version": "0.
|
27
|
-
"resolved": "https://registry.npmjs.org/katex/-/katex-0.
|
28
|
-
"integrity": "sha512-
|
29
|
-
"
|
30
|
-
"commander": "^
|
26
|
+
"node_modules/katex": {
|
27
|
+
"version": "0.13.5",
|
28
|
+
"resolved": "https://registry.npmjs.org/katex/-/katex-0.13.5.tgz",
|
29
|
+
"integrity": "sha512-n2uEzFpNFUOAlWs0eCgmT82LQyP+BlS45yBgnLRqe+ENp3+FEM3lM+cJwZwwxxONFgayyq1fm6n+w35vo2MaUg==",
|
30
|
+
"dependencies": {
|
31
|
+
"commander": "^6.0.0"
|
32
|
+
},
|
33
|
+
"bin": {
|
34
|
+
"katex": "cli.js"
|
31
35
|
}
|
32
36
|
},
|
33
|
-
"lunr": {
|
34
|
-
"version": "2.3.
|
35
|
-
"resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.
|
36
|
-
"integrity": "sha512-
|
37
|
+
"node_modules/lunr": {
|
38
|
+
"version": "2.3.9",
|
39
|
+
"resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
|
40
|
+
"integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
|
37
41
|
}
|
38
|
-
}
|
42
|
+
},
|
43
|
+
"dependencies": {}
|
39
44
|
}
|
data/js/package.json
CHANGED
data/lib/jazzy.rb
CHANGED
data/lib/jazzy/config.rb
CHANGED
@@ -1,3 +1,5 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
1
3
|
require 'optparse'
|
2
4
|
require 'pathname'
|
3
5
|
require 'uri'
|
@@ -8,7 +10,7 @@ require 'jazzy/source_declaration/access_control_level'
|
|
8
10
|
module Jazzy
|
9
11
|
# rubocop:disable Metrics/ClassLength
|
10
12
|
class Config
|
11
|
-
# rubocop:disable
|
13
|
+
# rubocop:disable Naming/AccessorMethodName
|
12
14
|
class Attribute
|
13
15
|
attr_reader :name, :description, :command_line, :config_file_key,
|
14
16
|
:default, :parse
|
@@ -50,6 +52,7 @@ module Jazzy
|
|
50
52
|
|
51
53
|
def attach_to_option_parser(config, opt)
|
52
54
|
return if command_line.empty?
|
55
|
+
|
53
56
|
opt.on(*command_line, *description) do |val|
|
54
57
|
set(config, val)
|
55
58
|
end
|
@@ -70,11 +73,12 @@ module Jazzy
|
|
70
73
|
end
|
71
74
|
end
|
72
75
|
end
|
73
|
-
# rubocop:enable
|
76
|
+
# rubocop:enable Naming/AccessorMethodName
|
74
77
|
|
75
78
|
def self.config_attr(name, **opts)
|
76
79
|
attr_accessor name
|
77
80
|
attr_accessor "#{name}_configured"
|
81
|
+
|
78
82
|
@all_config_attrs ||= []
|
79
83
|
@all_config_attrs << Attribute.new(name, **opts)
|
80
84
|
end
|
@@ -112,7 +116,7 @@ module Jazzy
|
|
112
116
|
|
113
117
|
# ──────── Build ────────
|
114
118
|
|
115
|
-
# rubocop:disable Layout/
|
119
|
+
# rubocop:disable Layout/ArgumentAlignment
|
116
120
|
|
117
121
|
config_attr :output,
|
118
122
|
description: 'Folder to output the HTML docs to',
|
@@ -124,7 +128,7 @@ module Jazzy
|
|
124
128
|
command_line: ['-c', '--[no-]clean'],
|
125
129
|
description: ['Delete contents of output directory before running. ',
|
126
130
|
'WARNING: If --output is set to ~/Desktop, this will '\
|
127
|
-
|
131
|
+
'delete the ~/Desktop directory.'],
|
128
132
|
default: false
|
129
133
|
|
130
134
|
config_attr :objc_mode,
|
@@ -150,10 +154,10 @@ module Jazzy
|
|
150
154
|
config_attr :hide_declarations,
|
151
155
|
command_line: '--hide-declarations [objc|swift] ',
|
152
156
|
description: 'Hide declarations in the specified language. Given that ' \
|
153
|
-
|
154
|
-
|
155
|
-
|
156
|
-
|
157
|
+
'generating Swift docs only generates Swift declarations, ' \
|
158
|
+
'this is useful for hiding a specific interface for ' \
|
159
|
+
'either Objective-C or mixed Objective-C and Swift ' \
|
160
|
+
'projects.',
|
157
161
|
default: ''
|
158
162
|
|
159
163
|
config_attr :keep_property_attributes,
|
@@ -170,7 +174,7 @@ module Jazzy
|
|
170
174
|
config_attr :build_tool_arguments,
|
171
175
|
command_line: ['-b', '--build-tool-arguments arg1,arg2,…argN', Array],
|
172
176
|
description: 'Arguments to forward to xcodebuild, swift build, or ' \
|
173
|
-
|
177
|
+
'sourcekitten.',
|
174
178
|
default: []
|
175
179
|
|
176
180
|
alias_config_attr :xcodebuild_arguments, :build_tool_arguments,
|
@@ -192,7 +196,7 @@ module Jazzy
|
|
192
196
|
config_attr :excluded_files,
|
193
197
|
command_line: ['-e', '--exclude filepath1,filepath2,…filepathN', Array],
|
194
198
|
description: 'Source file pathnames to be excluded from documentation. '\
|
195
|
-
|
199
|
+
'Supports wildcards.',
|
196
200
|
default: [],
|
197
201
|
parse: ->(files) do
|
198
202
|
Array(files).map { |f| expand_glob_path(f).to_s }
|
@@ -201,7 +205,7 @@ module Jazzy
|
|
201
205
|
config_attr :included_files,
|
202
206
|
command_line: ['-i', '--include filepath1,filepath2,…filepathN', Array],
|
203
207
|
description: 'Source file pathnames to be included in documentation. '\
|
204
|
-
|
208
|
+
'Supports wildcards.',
|
205
209
|
default: [],
|
206
210
|
parse: ->(files) do
|
207
211
|
Array(files).map { |f| expand_glob_path(f).to_s }
|
@@ -213,24 +217,26 @@ module Jazzy
|
|
213
217
|
parse: ->(v) do
|
214
218
|
if v.to_s.empty?
|
215
219
|
nil
|
220
|
+
elsif v.to_f < 2
|
221
|
+
raise 'jazzy only supports Swift 2.0 or later.'
|
216
222
|
else
|
217
|
-
raise 'jazzy only supports Swift 2.0 or later.' if v.to_f < 2
|
218
223
|
v
|
219
224
|
end
|
220
225
|
end
|
221
226
|
|
222
|
-
SWIFT_BUILD_TOOLS = %w[spm xcodebuild].freeze
|
227
|
+
SWIFT_BUILD_TOOLS = %w[spm xcodebuild symbolgraph].freeze
|
223
228
|
|
224
229
|
config_attr :swift_build_tool,
|
225
230
|
command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
|
226
|
-
description: 'Control whether Jazzy uses Swift Package Manager
|
227
|
-
|
228
|
-
|
229
|
-
|
231
|
+
description: 'Control whether Jazzy uses Swift Package Manager, '\
|
232
|
+
'xcodebuild, or swift-symbolgraph to build the module '\
|
233
|
+
'to be documented. By default it uses xcodebuild if '\
|
234
|
+
'there is a .xcodeproj file in the source directory.',
|
230
235
|
parse: ->(tool) do
|
231
236
|
return tool.to_sym if SWIFT_BUILD_TOOLS.include?(tool)
|
237
|
+
|
232
238
|
raise "Unsupported swift_build_tool #{tool}, "\
|
233
|
-
|
239
|
+
"supported values: #{SWIFT_BUILD_TOOLS.join(', ')}"
|
234
240
|
end
|
235
241
|
|
236
242
|
# ──────── Metadata ────────
|
@@ -253,14 +259,14 @@ module Jazzy
|
|
253
259
|
|
254
260
|
config_attr :version,
|
255
261
|
command_line: '--module-version VERSION',
|
256
|
-
description: 'Version string to use as part of the
|
257
|
-
|
262
|
+
description: 'Version string to use as part of the default docs '\
|
263
|
+
'title and inside the docset.',
|
258
264
|
default: '1.0'
|
259
265
|
|
260
266
|
config_attr :title,
|
261
267
|
command_line: '--title TITLE',
|
262
268
|
description: 'Title to display at the top of each page, overriding the '\
|
263
|
-
|
269
|
+
'default generated from module name and version.',
|
264
270
|
default: ''
|
265
271
|
|
266
272
|
config_attr :copyright,
|
@@ -285,16 +291,16 @@ module Jazzy
|
|
285
291
|
config_attr :podspec,
|
286
292
|
command_line: '--podspec FILEPATH',
|
287
293
|
description: 'A CocoaPods Podspec that describes the Swift library to '\
|
288
|
-
|
294
|
+
'document',
|
289
295
|
parse: ->(ps) { PodspecDocumenter.create_podspec(Pathname(ps)) if ps },
|
290
296
|
default: Dir['*.podspec{,.json}'].first
|
291
297
|
|
292
298
|
config_attr :pod_sources,
|
293
299
|
command_line: ['--pod-sources url1,url2,…urlN', Array],
|
294
300
|
description: 'A list of sources to find pod dependencies. Used only '\
|
295
|
-
|
296
|
-
|
297
|
-
|
301
|
+
'with --podspec when the podspec contains references to '\
|
302
|
+
'privately hosted pods. You must include the default pod '\
|
303
|
+
'source if public pods are also used.',
|
298
304
|
default: []
|
299
305
|
|
300
306
|
config_attr :docset_icon,
|
@@ -316,30 +322,56 @@ module Jazzy
|
|
316
322
|
config_attr :dash_url,
|
317
323
|
command_line: ['-d', '--dash_url URL'],
|
318
324
|
description: 'Location of the dash XML feed '\
|
319
|
-
|
325
|
+
'e.g. https://realm.io/docsets/realm.xml)',
|
320
326
|
parse: ->(d) { URI(d) }
|
321
327
|
|
322
|
-
|
323
|
-
|
324
|
-
|
325
|
-
|
328
|
+
SOURCE_HOSTS = %w[github gitlab bitbucket].freeze
|
329
|
+
|
330
|
+
config_attr :source_host,
|
331
|
+
command_line: "--source-host #{SOURCE_HOSTS.join(' | ')}",
|
332
|
+
description: ['The source-code hosting site to be linked from documentation.',
|
333
|
+
'This setting affects the logo image and link format.',
|
334
|
+
"Default: 'github'"],
|
335
|
+
default: 'github',
|
336
|
+
parse: ->(host) do
|
337
|
+
return host.to_sym if SOURCE_HOSTS.include?(host)
|
338
|
+
|
339
|
+
raise "Unsupported source_host '#{host}', "\
|
340
|
+
"supported values: #{SOURCE_HOSTS.join(', ')}"
|
341
|
+
end
|
342
|
+
|
343
|
+
config_attr :source_host_url,
|
344
|
+
command_line: ['--source-host-url URL'],
|
345
|
+
description: ["URL to link from the source host's logo.",
|
346
|
+
'For example https://github.com/realm/realm-cocoa'],
|
326
347
|
parse: ->(g) { URI(g) }
|
327
348
|
|
328
|
-
|
349
|
+
alias_config_attr :github_url, :source_host_url,
|
350
|
+
command_line: ['-g', '--github_url URL'],
|
351
|
+
description: 'Back-compatibility alias for source_host_url.'
|
352
|
+
|
353
|
+
config_attr :source_host_files_url,
|
354
|
+
command_line: '--source-host-files-url PREFIX',
|
355
|
+
description: [
|
356
|
+
"The base URL on the source host of the project's files, to link "\
|
357
|
+
'from individual declarations.',
|
358
|
+
'For example https://github.com/realm/realm-cocoa/tree/v0.87.1',
|
359
|
+
]
|
360
|
+
|
361
|
+
alias_config_attr :github_file_prefix, :source_host_files_url,
|
329
362
|
command_line: '--github-file-prefix PREFIX',
|
330
|
-
description: '
|
331
|
-
'https://github.com/realm/realm-cocoa/tree/v0.87.1)'
|
363
|
+
description: 'Back-compatibility alias for source_host_files_url'
|
332
364
|
|
333
365
|
config_attr :docset_playground_url,
|
334
366
|
command_line: '--docset-playground-url URL',
|
335
367
|
description: 'URL of an interactive playground to demonstrate the '\
|
336
|
-
|
368
|
+
'framework, linked to from the docset.'
|
337
369
|
|
338
370
|
# ──────── Doc generation options ────────
|
339
371
|
config_attr :disable_search,
|
340
372
|
command_line: '--disable-search',
|
341
|
-
description:
|
342
|
-
|
373
|
+
description: 'Avoid generating a search index. '\
|
374
|
+
'Search is available in some themes.',
|
343
375
|
default: false
|
344
376
|
|
345
377
|
config_attr :skip_documentation,
|
@@ -359,7 +391,7 @@ module Jazzy
|
|
359
391
|
config_attr :skip_undocumented,
|
360
392
|
command_line: '--[no-]skip-undocumented',
|
361
393
|
description: "Don't document declarations that have no documentation "\
|
362
|
-
|
394
|
+
'comments.',
|
363
395
|
default: false
|
364
396
|
|
365
397
|
config_attr :hide_documentation_coverage,
|
@@ -368,22 +400,22 @@ module Jazzy
|
|
368
400
|
default: false
|
369
401
|
|
370
402
|
config_attr :custom_categories,
|
371
|
-
description:
|
372
|
-
|
373
|
-
|
374
|
-
|
403
|
+
description: 'Custom navigation categories to replace the standard '\
|
404
|
+
"'Classes', 'Protocols', etc. Types not explicitly named "\
|
405
|
+
'in a custom category appear in generic groups at the '\
|
406
|
+
'end. Example: https://git.io/v4Bcp',
|
375
407
|
default: []
|
376
408
|
|
377
409
|
config_attr :custom_categories_unlisted_prefix,
|
378
410
|
description: "Prefix for navigation section names that aren't "\
|
379
|
-
|
411
|
+
'explicitly listed in `custom_categories`.',
|
380
412
|
default: 'Other '
|
381
413
|
|
382
414
|
config_attr :hide_unlisted_documentation,
|
383
415
|
command_line: '--[no-]hide-unlisted-documentation',
|
384
416
|
description: "Don't include documentation in the sidebar from the "\
|
385
|
-
|
386
|
-
|
417
|
+
"`documentation` config value that aren't explicitly "\
|
418
|
+
'listed in `custom_categories`.',
|
387
419
|
default: false
|
388
420
|
|
389
421
|
config_attr :custom_head,
|
@@ -391,15 +423,15 @@ module Jazzy
|
|
391
423
|
description: 'Custom HTML to inject into <head></head>.',
|
392
424
|
default: ''
|
393
425
|
|
394
|
-
BUILTIN_THEME_DIR = Pathname(
|
426
|
+
BUILTIN_THEME_DIR = Pathname(__dir__) + 'themes'
|
395
427
|
BUILTIN_THEMES = BUILTIN_THEME_DIR.children(false).map(&:to_s)
|
396
428
|
|
397
429
|
config_attr :theme_directory,
|
398
430
|
command_line: "--theme [#{BUILTIN_THEMES.join(' | ')} | DIRPATH]",
|
399
431
|
description: "Which theme to use. Specify either 'apple' (default), "\
|
400
|
-
|
401
|
-
|
402
|
-
|
432
|
+
'one of the other built-in theme names, or the path to '\
|
433
|
+
'your mustache templates and other assets for a custom '\
|
434
|
+
'theme.',
|
403
435
|
default: 'apple',
|
404
436
|
parse: ->(t) do
|
405
437
|
if BUILTIN_THEMES.include?(t)
|
@@ -412,9 +444,9 @@ module Jazzy
|
|
412
444
|
config_attr :use_safe_filenames,
|
413
445
|
command_line: '--use-safe-filenames',
|
414
446
|
description: 'Replace unsafe characters in filenames with an encoded '\
|
415
|
-
|
416
|
-
|
417
|
-
|
447
|
+
'representation. This will reduce human readability of '\
|
448
|
+
'some URLs, but may be necessary for projects that '\
|
449
|
+
'expose filename-unfriendly functions such as /(_:_:)',
|
418
450
|
default: false
|
419
451
|
|
420
452
|
config_attr :template_directory,
|
@@ -434,10 +466,17 @@ module Jazzy
|
|
434
466
|
config_attr :undocumented_text,
|
435
467
|
command_line: '--undocumented-text UNDOCUMENTED_TEXT',
|
436
468
|
description: 'Default text for undocumented symbols. The default '\
|
437
|
-
|
469
|
+
'is "Undocumented", put "" if no text is required',
|
438
470
|
default: 'Undocumented'
|
439
471
|
|
440
|
-
|
472
|
+
config_attr :separate_global_declarations,
|
473
|
+
command_line: '--[no-]separate-global-declarations',
|
474
|
+
description: 'Create separate pages for all global declarations '\
|
475
|
+
"(classes, structures, enums etc.) even if they don't "\
|
476
|
+
'have children.',
|
477
|
+
default: false
|
478
|
+
|
479
|
+
# rubocop:enable Layout/ArgumentAlignment
|
441
480
|
|
442
481
|
def initialize
|
443
482
|
self.class.all_config_attrs.each do |attr|
|
@@ -450,7 +489,6 @@ module Jazzy
|
|
450
489
|
Doc.template_path = theme_directory + 'templates'
|
451
490
|
end
|
452
491
|
|
453
|
-
# rubocop:disable Metrics/MethodLength
|
454
492
|
def self.parse!
|
455
493
|
config = new
|
456
494
|
config.parse_command_line
|
@@ -464,9 +502,16 @@ module Jazzy
|
|
464
502
|
)
|
465
503
|
end
|
466
504
|
|
505
|
+
config.validate
|
506
|
+
|
467
507
|
config
|
468
508
|
end
|
469
509
|
|
510
|
+
def warning(message)
|
511
|
+
warn "WARNING: #{message}"
|
512
|
+
end
|
513
|
+
|
514
|
+
# rubocop:disable Metrics/MethodLength
|
470
515
|
def parse_command_line
|
471
516
|
OptionParser.new do |opt|
|
472
517
|
opt.banner = 'Usage: jazzy'
|
@@ -478,7 +523,7 @@ module Jazzy
|
|
478
523
|
end
|
479
524
|
|
480
525
|
opt.on('-v', '--version', 'Print version number') do
|
481
|
-
puts
|
526
|
+
puts "jazzy version: #{Jazzy::VERSION}"
|
482
527
|
exit
|
483
528
|
end
|
484
529
|
|
@@ -497,6 +542,10 @@ module Jazzy
|
|
497
542
|
exit
|
498
543
|
end
|
499
544
|
end.parse!
|
545
|
+
|
546
|
+
unless ARGV.empty?
|
547
|
+
warning "Leftover unused command-line text: #{ARGV}"
|
548
|
+
end
|
500
549
|
end
|
501
550
|
|
502
551
|
def parse_config_file
|
@@ -514,13 +563,12 @@ module Jazzy
|
|
514
563
|
|
515
564
|
config_file.each do |key, value|
|
516
565
|
unless attr = attrs_by_conf_key[key]
|
517
|
-
message = "
|
566
|
+
message = "Unknown config file attribute #{key.inspect}"
|
518
567
|
if matching_name = attrs_by_name[key]
|
519
|
-
message
|
520
|
-
|
521
|
-
message << '?)'
|
568
|
+
message +=
|
569
|
+
" (Did you mean #{matching_name.first.config_file_key.inspect}?)"
|
522
570
|
end
|
523
|
-
|
571
|
+
warning message
|
524
572
|
next
|
525
573
|
end
|
526
574
|
|
@@ -530,6 +578,17 @@ module Jazzy
|
|
530
578
|
self.base_path = nil
|
531
579
|
end
|
532
580
|
|
581
|
+
def validate
|
582
|
+
if source_host_configured &&
|
583
|
+
source_host_url.nil? &&
|
584
|
+
source_host_files_url.nil?
|
585
|
+
warning 'Option `source_host` is set but has no effect without either '\
|
586
|
+
'`source_host_url` or `source_host_files_url`.'
|
587
|
+
end
|
588
|
+
end
|
589
|
+
|
590
|
+
# rubocop:enable Metrics/MethodLength
|
591
|
+
|
533
592
|
def locate_config_file
|
534
593
|
return config_file if config_file
|
535
594
|
|
@@ -543,15 +602,10 @@ module Jazzy
|
|
543
602
|
|
544
603
|
def read_config_file(file)
|
545
604
|
case File.extname(file)
|
546
|
-
when '.json'
|
547
|
-
|
548
|
-
|
549
|
-
|
550
|
-
else
|
551
|
-
# rubocop:disable Security/YAMLLoad
|
552
|
-
YAML.load(File.read(file))
|
553
|
-
# rubocop:enable Security/YAMLLoad
|
554
|
-
end
|
605
|
+
when '.json'
|
606
|
+
JSON.parse(File.read(file))
|
607
|
+
when '.yaml', '.yml'
|
608
|
+
YAML.safe_load(File.read(file))
|
555
609
|
else raise "Config file must be .yaml or .json, but got #{file.inspect}"
|
556
610
|
end
|
557
611
|
end
|
@@ -568,7 +622,7 @@ module Jazzy
|
|
568
622
|
|
569
623
|
The config file can be in YAML or JSON format. Available options are:
|
570
624
|
|
571
|
-
|
625
|
+
_EOS_
|
572
626
|
.gsub(/^ +/, '')
|
573
627
|
|
574
628
|
print_option_help
|