jazzy 0.13.4 → 0.14.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (146) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/Tests.yml +52 -0
  3. data/.rubocop.yml +123 -24
  4. data/CHANGELOG.md +103 -0
  5. data/CONTRIBUTING.md +5 -5
  6. data/Dangerfile +11 -8
  7. data/Gemfile +3 -1
  8. data/Gemfile.lock +91 -69
  9. data/README.md +85 -13
  10. data/Rakefile +19 -13
  11. data/bin/jazzy +3 -2
  12. data/bin/sourcekitten +0 -0
  13. data/jazzy.gemspec +8 -6
  14. data/js/package-lock.json +30 -25
  15. data/js/package.json +3 -3
  16. data/lib/jazzy.rb +2 -0
  17. data/lib/jazzy/config.rb +124 -70
  18. data/lib/jazzy/doc.rb +3 -1
  19. data/lib/jazzy/doc_builder.rb +75 -81
  20. data/lib/jazzy/docset_builder.rb +3 -1
  21. data/lib/jazzy/documentation_generator.rb +6 -2
  22. data/lib/jazzy/executable.rb +3 -0
  23. data/lib/jazzy/extensions/bitbucket/img/bitbucket.svg +11 -0
  24. data/lib/jazzy/{themes/apple/assets → extensions/github}/img/gh.png +0 -0
  25. data/lib/jazzy/extensions/gitlab/img/gitlab.svg +23 -0
  26. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.ttf +0 -0
  27. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff +0 -0
  28. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff2 +0 -0
  29. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.ttf +0 -0
  30. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff +0 -0
  31. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff2 +0 -0
  32. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.ttf +0 -0
  33. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff +0 -0
  34. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff2 +0 -0
  35. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.ttf +0 -0
  36. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff +0 -0
  37. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff2 +0 -0
  38. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.ttf +0 -0
  39. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff +0 -0
  40. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff2 +0 -0
  41. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.ttf +0 -0
  42. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff +0 -0
  43. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff2 +0 -0
  44. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.ttf +0 -0
  45. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff +0 -0
  46. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff2 +0 -0
  47. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.ttf +0 -0
  48. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff +0 -0
  49. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff2 +0 -0
  50. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.ttf +0 -0
  51. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff +0 -0
  52. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff2 +0 -0
  53. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.ttf +0 -0
  54. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff +0 -0
  55. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff2 +0 -0
  56. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.ttf +0 -0
  57. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff +0 -0
  58. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff2 +0 -0
  59. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.ttf +0 -0
  60. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff +0 -0
  61. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff2 +0 -0
  62. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.ttf +0 -0
  63. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff +0 -0
  64. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff2 +0 -0
  65. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.ttf +0 -0
  66. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff +0 -0
  67. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff2 +0 -0
  68. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.ttf +0 -0
  69. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff +0 -0
  70. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff2 +0 -0
  71. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.ttf +0 -0
  72. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff +0 -0
  73. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff2 +0 -0
  74. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.ttf +0 -0
  75. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff +0 -0
  76. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff2 +0 -0
  77. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.ttf +0 -0
  78. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff +0 -0
  79. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff2 +0 -0
  80. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.ttf +0 -0
  81. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff +0 -0
  82. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff2 +0 -0
  83. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.ttf +0 -0
  84. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff +0 -0
  85. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff2 +0 -0
  86. data/lib/jazzy/extensions/katex/css/katex.min.css +1 -1
  87. data/lib/jazzy/extensions/katex/js/katex.min.js +1 -1
  88. data/lib/jazzy/gem_version.rb +3 -1
  89. data/lib/jazzy/highlighter.rb +5 -3
  90. data/lib/jazzy/jazzy_markdown.rb +101 -30
  91. data/lib/jazzy/podspec_documenter.rb +14 -16
  92. data/lib/jazzy/search_builder.rb +4 -3
  93. data/lib/jazzy/source_declaration.rb +24 -5
  94. data/lib/jazzy/source_declaration/access_control_level.rb +7 -5
  95. data/lib/jazzy/source_declaration/type.rb +33 -1
  96. data/lib/jazzy/source_document.rb +8 -5
  97. data/lib/jazzy/source_host.rb +111 -0
  98. data/lib/jazzy/source_mark.rb +8 -6
  99. data/lib/jazzy/source_module.rb +6 -6
  100. data/lib/jazzy/sourcekitten.rb +105 -79
  101. data/lib/jazzy/stats.rb +4 -2
  102. data/lib/jazzy/symbol_graph.rb +95 -0
  103. data/lib/jazzy/symbol_graph/constraint.rb +98 -0
  104. data/lib/jazzy/symbol_graph/ext_node.rb +116 -0
  105. data/lib/jazzy/symbol_graph/graph.rb +195 -0
  106. data/lib/jazzy/symbol_graph/relationship.rb +42 -0
  107. data/lib/jazzy/symbol_graph/sym_node.rb +163 -0
  108. data/lib/jazzy/symbol_graph/symbol.rb +222 -0
  109. data/lib/jazzy/themes/apple/assets/css/highlight.css.scss +63 -59
  110. data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss +101 -4
  111. data/lib/jazzy/themes/apple/assets/img/spinner.gif +0 -0
  112. data/lib/jazzy/themes/apple/assets/js/jazzy.js +4 -0
  113. data/lib/jazzy/themes/apple/assets/js/jazzy.search.js +74 -0
  114. data/lib/jazzy/themes/apple/assets/js/jquery.min.js +2 -2
  115. data/lib/jazzy/themes/apple/assets/js/lunr.min.js +6 -0
  116. data/lib/jazzy/themes/apple/assets/js/typeahead.jquery.js +1694 -0
  117. data/lib/jazzy/themes/apple/templates/doc.mustache +35 -0
  118. data/lib/jazzy/themes/apple/templates/footer.mustache +1 -1
  119. data/lib/jazzy/themes/apple/templates/header.mustache +10 -3
  120. data/lib/jazzy/themes/apple/templates/task.mustache +4 -4
  121. data/lib/jazzy/themes/fullwidth/assets/css/highlight.css.scss +63 -59
  122. data/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss +11 -2
  123. data/lib/jazzy/themes/fullwidth/assets/js/jazzy.js +4 -0
  124. data/lib/jazzy/themes/fullwidth/assets/js/jazzy.search.js +4 -0
  125. data/lib/jazzy/themes/fullwidth/assets/js/jquery.min.js +2 -2
  126. data/lib/jazzy/themes/fullwidth/assets/js/lunr.min.js +3 -3
  127. data/lib/jazzy/themes/fullwidth/templates/doc.mustache +30 -0
  128. data/lib/jazzy/themes/fullwidth/templates/footer.mustache +1 -1
  129. data/lib/jazzy/themes/fullwidth/templates/header.mustache +5 -5
  130. data/lib/jazzy/themes/fullwidth/templates/task.mustache +4 -4
  131. data/lib/jazzy/themes/jony/assets/css/highlight.css.scss +63 -59
  132. data/lib/jazzy/themes/jony/assets/css/jazzy.css.scss +34 -2
  133. data/lib/jazzy/themes/jony/assets/js/jazzy.js +4 -0
  134. data/lib/jazzy/themes/jony/assets/js/jquery.min.js +2 -2
  135. data/lib/jazzy/themes/jony/templates/doc.mustache +30 -0
  136. data/lib/jazzy/themes/jony/templates/footer.mustache +1 -1
  137. data/lib/jazzy/themes/jony/templates/header.mustache +5 -5
  138. data/lib/jazzy/themes/jony/templates/task.mustache +4 -4
  139. data/spec/integration_spec.rb +54 -42
  140. data/spec/spec_helper.rb +3 -1
  141. data/spec/spec_helper/pre_flight.rb +2 -0
  142. metadata +43 -19
  143. data/.circleci/config.yml +0 -83
  144. data/lib/jazzy/themes/fullwidth/assets/img/gh.png +0 -0
  145. data/lib/jazzy/themes/jony/assets/img/gh.png +0 -0
  146. 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
- $stderr.puts "\033[0;31m" \
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 lib spec'
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
- $stderr.puts "\033[0;31m" \
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
- $stderr.puts e.message
143
- $stderr.puts e.backtrace
144
- $stderr.puts
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('../../Gemfile', __FILE__)
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('../../lib', __FILE__)
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
- "Run in your Xcode project's root directory for " \
13
- 'instant HTML docs.'
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 << 'jazzy'
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.7'
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.0.0'
34
+ spec.required_ruby_version = '>= 2.6.3'
33
35
  end
data/js/package-lock.json CHANGED
@@ -1,39 +1,44 @@
1
1
  {
2
- "name": "jazzy-js",
3
- "version": "1.0.0",
4
- "lockfileVersion": 1,
2
+ "lockfileVersion": 2,
5
3
  "requires": true,
6
- "dependencies": {
7
- "commander": {
8
- "version": "2.20.3",
9
- "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
10
- "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ=="
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
- "requires": {
17
+ "dependencies": {
17
18
  "jquery": ">=1.11"
18
19
  }
19
20
  },
20
- "jquery": {
21
- "version": "3.5.1",
22
- "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.5.1.tgz",
23
- "integrity": "sha512-XwIBPqcMn57FxfT+Go5pzySnm4KWkT1Tv7gjrpT1srtf8Weynl6R273VJ5GjkRb51IzMp5nbaPjJXMWeju2MKg=="
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.11.1",
27
- "resolved": "https://registry.npmjs.org/katex/-/katex-0.11.1.tgz",
28
- "integrity": "sha512-5oANDICCTX0NqYIyAiFCCwjQ7ERu3DQG2JFHLbYOf+fXaMoH8eg/zOq5WSYJsKMi/QebW+Eh3gSM+oss1H/bww==",
29
- "requires": {
30
- "commander": "^2.19.0"
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.8",
35
- "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.8.tgz",
36
- "integrity": "sha512-oxMeX/Y35PNFuZoHp+jUj5OSEmLCaIH4KTFJh7a93cHBoFmpw2IoPs22VIz7vyO2YUnx2Tn9dzIwO2P/4quIRg=="
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
@@ -10,8 +10,8 @@
10
10
  "license": "MIT",
11
11
  "dependencies": {
12
12
  "corejs-typeahead": "^1.3.1",
13
- "jquery": "^3.5.1",
14
- "katex": "^0.11.1",
15
- "lunr": "^2.3.8"
13
+ "jquery": "^3.6.0",
14
+ "katex": "^0.13.3",
15
+ "lunr": "^2.3.9"
16
16
  }
17
17
  }
data/lib/jazzy.rb CHANGED
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'jazzy/config'
2
4
  require 'jazzy/doc_builder'
3
5
 
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 Style/AccessorMethodName
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 Style/AccessorMethodName
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/AlignParameters
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
- 'delete the ~/Desktop directory.'],
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
- 'generating Swift docs only generates Swift declarations, ' \
154
- 'this is useful for hiding a specific interface for ' \
155
- 'either Objective-C or mixed Objective-C and Swift ' \
156
- 'projects.',
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
- 'sourcekitten.',
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
- 'Supports wildcards.',
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
- 'Supports wildcards.',
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 or '\
227
- 'xcodebuild to build the module to be documented. By '\
228
- 'default it uses xcodebuild if there is a .xcodeproj '\
229
- 'file in the source directory.',
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
- "supported values: #{SWIFT_BUILD_TOOLS.join(', ')}"
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 the default docs '\
257
- 'title and inside the docset.',
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
- 'default generated from module name and version.',
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
- 'document',
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
- 'with --podspec when the podspec contains references to '\
296
- 'privately hosted pods. You must include the default pod '\
297
- 'source if public pods are also used.',
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
- 'e.g. https://realm.io/docsets/realm.xml)',
325
+ 'e.g. https://realm.io/docsets/realm.xml)',
320
326
  parse: ->(d) { URI(d) }
321
327
 
322
- config_attr :github_url,
323
- command_line: ['-g', '--github_url URL'],
324
- description: 'GitHub URL of this project (e.g. '\
325
- 'https://github.com/realm/realm-cocoa)',
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
- config_attr :github_file_prefix,
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: 'GitHub URL file prefix of this project (e.g. '\
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
- 'framework, linked to from the docset.'
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: ['Avoid generating a search index. '\
342
- 'Search is available in some themes.'],
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
- 'comments.',
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: ['Custom navigation categories to replace the standard '\
372
- 'Classes, Protocols, etc.”', 'Types not explicitly named '\
373
- 'in a custom category appear in generic groups at the end.',
374
- 'Example: https://git.io/v4Bcp'],
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
- 'explicitly listed in `custom_categories`.',
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
- "`documentation` config value that aren't explicitly "\
386
- 'listed in `custom_categories`.',
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(__FILE__).parent + 'themes'
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
- 'one of the other built-in theme names, or the path to '\
401
- 'your mustache templates and other assets for a custom '\
402
- 'theme.',
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
- 'representation. This will reduce human readability of '\
416
- 'some URLs, but may be necessary for projects that '\
417
- 'expose filename-unfriendly functions such as /(_:_:)',
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
- 'is "Undocumented", put "" if no text is required',
469
+ 'is "Undocumented", put "" if no text is required',
438
470
  default: 'Undocumented'
439
471
 
440
- # rubocop:enable Style/AlignParameter
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 'jazzy version: ' + Jazzy::VERSION
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 = "WARNING: Unknown config file attribute #{key.inspect}"
566
+ message = "Unknown config file attribute #{key.inspect}"
518
567
  if matching_name = attrs_by_name[key]
519
- message << ' (Did you mean '
520
- message << matching_name.first.config_file_key.inspect
521
- message << '?)'
568
+ message +=
569
+ " (Did you mean #{matching_name.first.config_file_key.inspect}?)"
522
570
  end
523
- warn message
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' then JSON.parse(File.read(file))
547
- when '.yaml', '.yml' then
548
- if YAML.respond_to?('safe_load') # ruby >= 2.1.0
549
- YAML.safe_load(File.read(file))
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
- _EOS_
625
+ _EOS_
572
626
  .gsub(/^ +/, '')
573
627
 
574
628
  print_option_help