jazzy 0.13.0 → 0.13.5

data/Rakefile

@@ -109,6 +109,36 @@ begin
     FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
   end
 
+  #-- Theme Dependencies -----------------------------------------------------#
+
+  THEME_FILES = {
+    'jquery/dist/jquery.min.js' => [
+      'themes/apple/assets/js',
+      'themes/fullwidth/assets/js',
+      'themes/jony/assets/js'
+    ],
+    'lunr/lunr.min.js' => [
+      'themes/apple/assets/js',
+      'themes/fullwidth/assets/js'
+    ],
+    'corejs-typeahead/dist/typeahead.jquery.js' => [
+      'themes/apple/assets/js',
+      'themes/fullwidth/assets/js'
+    ],
+    'katex/dist/katex.min.css' => ['extensions/katex/css'],
+    'katex/dist/fonts' => ['extensions/katex/css'],
+    'katex/dist/katex.min.js' => ['extensions/katex/js']
+  }
+
+  desc 'Copies theme dependencies (`npm update/install` by hand first)'
+  task :theme_deps do
+    THEME_FILES.each_pair do |src, dsts|
+      dsts.each do |dst|
+        FileUtils.cp_r "js/node_modules/#{src}", "lib/jazzy/#{dst}"
+      end
+    end
+  end
+
 rescue LoadError, NameError => e
   $stderr.puts "\033[0;31m" \
     '[!] Some Rake tasks haven been disabled because the environment' \

data/jazzy.gemspec

@@ -5,8 +5,8 @@ require File.expand_path('lib/jazzy/gem_version.rb', File.dirname(__FILE__))
 Gem::Specification.new do |spec|
   spec.name          = 'jazzy'
   spec.version       = Jazzy::VERSION
-  spec.authors       = ['JP Simard', 'Tim Anglade', 'Samuel Giddins']
-  spec.email         = ['jp@realm.io']
+  spec.authors       = ['JP Simard', 'Tim Anglade', 'Samuel Giddins', 'John Fairhurst']
+  spec.email         = ['jp@jpsim.com']
   spec.summary       = 'Soulful docs for Swift & Objective-C.'
   spec.description   = 'Soulful docs for Swift & Objective-C. ' \
                        "Run in your Xcode project's root directory for " \
@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'xcinvoke', '~> 0.3.0'
 
   spec.add_development_dependency 'bundler', '~> 1.7'
-  spec.add_development_dependency 'rake', '~> 10.3'
+  spec.add_development_dependency 'rake', '~> 13.0'
 
   spec.required_ruby_version = '>= 2.0.0'
 end

data/js/package-lock.json

@@ -0,0 +1,39 @@
+{
+  "name": "jazzy-js",
+  "version": "1.0.0",
+  "lockfileVersion": 1,
+  "requires": true,
+  "dependencies": {
+    "commander": {
+      "version": "2.20.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
+      "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ=="
+    },
+    "corejs-typeahead": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.1.tgz",
+      "integrity": "sha512-fyNlBNWJNL6EQUnJyAunEzBzRcwR2cEHtZXBi2pndHPOJ/wpOf3wbS+/Oh+kYYS5sKowQcs0LFwMSl6Y2Xeqkw==",
+      "requires": {
+        "jquery": ">=1.11"
+      }
+    },
+    "jquery": {
+      "version": "3.5.1",
+      "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.5.1.tgz",
+      "integrity": "sha512-XwIBPqcMn57FxfT+Go5pzySnm4KWkT1Tv7gjrpT1srtf8Weynl6R273VJ5GjkRb51IzMp5nbaPjJXMWeju2MKg=="
+    },
+    "katex": {
+      "version": "0.11.1",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.11.1.tgz",
+      "integrity": "sha512-5oANDICCTX0NqYIyAiFCCwjQ7ERu3DQG2JFHLbYOf+fXaMoH8eg/zOq5WSYJsKMi/QebW+Eh3gSM+oss1H/bww==",
+      "requires": {
+        "commander": "^2.19.0"
+      }
+    },
+    "lunr": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.8.tgz",
+      "integrity": "sha512-oxMeX/Y35PNFuZoHp+jUj5OSEmLCaIH4KTFJh7a93cHBoFmpw2IoPs22VIz7vyO2YUnx2Tn9dzIwO2P/4quIRg=="
+    }
+  }
+}

data/js/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "jazzy-js",
+  "version": "1.0.0",
+  "description": "Jazzy theme dependencies",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "corejs-typeahead": "^1.3.1",
+    "jquery": "^3.5.1",
+    "katex": "^0.11.1",
+    "lunr": "^2.3.8"
+  }
+}

data/lib/jazzy/config.rb

@@ -59,7 +59,7 @@ module Jazzy
 
       def full_command_line_name
         long_option_names = command_line.map do |opt|
-          Regexp.last_match(1) if opt =~ %r{
+          Regexp.last_match(1) if opt.to_s =~ %r{
             ^--           # starts with double dash
             (?:\[no-\])?  # optional prefix for booleans
             ([^\s]+)      # long option name
@@ -156,6 +156,11 @@ module Jazzy
                    'projects.',
       default: ''
 
+    config_attr :keep_property_attributes,
+      command_line: '--[no-]keep-property-attributes',
+      description: 'Include the default Objective-C property attributes.',
+      default: false
+
     config_attr :config_file,
       command_line: '--config PATH',
       description: ['Configuration file (.yaml or .json)',
@@ -284,6 +289,14 @@ module Jazzy
       parse: ->(ps) { PodspecDocumenter.create_podspec(Pathname(ps)) if ps },
       default: Dir['*.podspec{,.json}'].first
 
+    config_attr :pod_sources,
+      command_line: ['--pod-sources url1,url2,…urlN', Array],
+      description: 'A list of sources to find pod dependencies. Used only '\
+                   'with --podspec when the podspec contains references to '\
+                   'privately hosted pods. You must include the default pod '\
+                   'source if public pods are also used.',
+      default: []
+
     config_attr :docset_icon,
       command_line: '--docset-icon FILEPATH',
       parse: ->(di) { expand_path(di) }
@@ -297,7 +310,8 @@ module Jazzy
     config_attr :root_url,
       command_line: ['-r', '--root-url URL'],
       description: 'Absolute URL root where these docs will be stored',
-      parse: ->(r) { URI(r) }
+      # ensure trailing slash for correct URI.join()
+      parse: ->(r) { URI(r.sub(%r{/?$}, '/')) }
 
     config_attr :dash_url,
       command_line: ['-d', '--dash_url URL'],
@@ -316,6 +330,11 @@ module Jazzy
       description: 'GitHub URL file prefix of this project (e.g. '\
                    'https://github.com/realm/realm-cocoa/tree/v0.87.1)'
 
+    config_attr :docset_playground_url,
+      command_line: '--docset-playground-url URL',
+      description: 'URL of an interactive playground to demonstrate the '\
+                   'framework, linked to from the docset.'
+
     # ──────── Doc generation options ────────
     config_attr :disable_search,
       command_line: '--disable-search',
@@ -355,6 +374,18 @@ module Jazzy
                     'Example: https://git.io/v4Bcp'],
       default: []
 
+    config_attr :custom_categories_unlisted_prefix,
+      description: "Prefix for navigation section names that aren't "\
+                   'explicitly listed in `custom_categories`.',
+      default: 'Other '
+
+    config_attr :hide_unlisted_documentation,
+      command_line: '--[no-]hide-unlisted-documentation',
+      description: "Don't include documentation in the sidebar from the "\
+                   "`documentation` config value that aren't explicitly "\
+                   'listed in `custom_categories`.',
+      default: false
+
     config_attr :custom_head,
       command_line: '--head HTML',
       description: 'Custom HTML to inject into <head></head>.',
@@ -406,6 +437,13 @@ module Jazzy
                    'is "Undocumented", put "" if no text is required',
       default: 'Undocumented'
 
+    config_attr :separate_global_declarations,
+      command_line: '--[no-]separate-global-declarations',
+      description: 'Create separate pages for all global declarations '\
+                   "(classes, structures, enums etc.) even if they don't "\
+                   'have children.',
+      default: false
+
     # rubocop:enable Style/AlignParameter
 
     def initialize

data/lib/jazzy/doc.rb

@@ -51,5 +51,9 @@ module Jazzy
         "#{config.module_name} Docs"
       end
     end
+
+    def enable_katex
+      Markdown.has_math
+    end
   end
 end

data/lib/jazzy/doc_builder.rb

@@ -29,23 +29,36 @@ module Jazzy
     # @return [Array] doc structure comprised of
     #                     section names & child names & URLs
     def self.doc_structure_for_docs(docs)
-      docs.map do |doc|
-        children = doc.children
-                      .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
-                      .flat_map do |child|
-          # FIXME: include arbitrarily nested extensible types
-          [{ name: child.name, url: child.url }] +
-            Array(child.children.select do |sub_child|
-              sub_child.type.swift_extensible? || sub_child.type.extension?
-            end).map do |sub_child|
-              { name: "– #{sub_child.name}", url: sub_child.url }
-            end
+      docs
+        .map do |doc|
+          children = children_for_doc(doc)
+          {
+            section: doc.name,
+            url: doc.url,
+            children: children,
+          }
         end
-        {
-          section: doc.name,
-          url: doc.url,
-          children: children,
-        }
+        .select do |structure|
+          if Config.instance.hide_unlisted_documentation
+            unlisted_prefix = Config.instance.custom_categories_unlisted_prefix
+            structure[:section] != "#{unlisted_prefix}Guides"
+          else
+            true
+          end
+        end
+    end
+
+    def self.children_for_doc(doc)
+      doc.children
+         .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
+         .flat_map do |child|
+        # FIXME: include arbitrarily nested extensible types
+        [{ name: child.name, url: child.url }] +
+          Array(child.children.select do |sub_child|
+            sub_child.type.swift_extensible? || sub_child.type.extension?
+          end).map do |sub_child|
+            { name: "– #{sub_child.name}", url: sub_child.url }
+          end
       end
     end
 
@@ -117,6 +130,7 @@ module Jazzy
       end
 
       copy_assets(output_dir)
+      copy_extensions(output_dir)
 
       DocsetBuilder.new(output_dir, source_module).build!
 
@@ -197,6 +211,15 @@ module Jazzy
       end
     end
 
+    def self.copy_extensions(destination)
+      copy_extension('katex', destination) if Markdown.has_math
+    end
+
+    def self.copy_extension(name, destination)
+      ext_directory = Pathname(__FILE__).parent + 'extensions/' + name
+      FileUtils.cp_r(ext_directory.children, destination)
+    end
+
     def self.render(doc_model, markdown)
       html = Markdown.render(markdown)
       SourceKitten.autolink_document(html, doc_model)
@@ -328,6 +351,7 @@ module Jazzy
       abstract = (item.abstract || '') + (item.discussion || '')
       {
         name:                       item.name,
+        name_html:                  item.name.gsub(':', ':<wbr>'),
         abstract:                   abstract,
         declaration:                item.display_declaration,
         language:                   item.display_language,
@@ -354,7 +378,7 @@ module Jazzy
       {
         name: mark.name,
         name_html: (render(doc_model, mark.name) if mark.name),
-        uid: URI.encode(uid),
+        uid: ERB::Util.url_encode(uid),
         items: items,
         pre_separator: mark.has_start_dash,
         post_separator: mark.has_end_dash,
@@ -408,12 +432,18 @@ module Jazzy
       doc[:kind] = doc_model.type.name
       doc[:dash_type] = doc_model.type.dash_type
       doc[:declaration] = doc_model.display_declaration
+      doc[:language] = doc_model.display_language
+      doc[:other_language_declaration] =
+        doc_model.display_other_language_declaration
       doc[:overview] = overview
+      doc[:parameters] = doc_model.parameters
+      doc[:return] = doc_model.return
       doc[:structure] = source_module.doc_structure
       doc[:tasks] = render_tasks(source_module, doc_model.children)
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
       doc[:github_url] = source_module.github_url
+      doc[:github_token_url] = gh_token_url(doc_model, source_module)
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:deprecation_message] = doc_model.deprecation_message

data/lib/jazzy/docset_builder.rb

@@ -43,6 +43,8 @@ module Jazzy
             template.read,
             lowercase_name: source_module.name.downcase,
             name: source_module.name,
+            root_url: config.root_url,
+            playground_url: config.docset_playground_url,
           )
         end
       end

data/lib/jazzy/docset_builder/info_plist.mustache

@@ -16,5 +16,13 @@
       <true/>
     <key>DashDocSetFamily</key>
       <string>dashtoc</string>
+    {{#root_url}}
+    <key>DashDocSetFallbackURL</key>
+      <string>{{{.}}}</string>
+    {{/root_url}}
+    {{#playground_url}}
+    <key>DashDocSetPlayURL</key>
+      <string>{{{.}}}</string>
+    {{/playground_url}}
   </dict>
 </plist>