jazzy 0.13.4 → 0.13.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6614bb5a4465f50a9f0188ec56ad872d82963245f790c1815b650452be8d652
-  data.tar.gz: d807b40f914ca121eeaf8ff72016300f9da340f54aeeab310319a40c1bb90d3b
+  metadata.gz: 9b896e2cc19ed17de08bbaf77655ce4cc28ba3b086c4b324c6f3c15d3f61c5c2
+  data.tar.gz: 6dda6fa99cc9c4282f3818f405f218b23d22e57b6869be208082e36b25873dd0
 SHA512:
-  metadata.gz: cedba7374e64a603835c5270b1dcd57d79b79536fd9bc434995e35c223f55c6b100628296233e7370c7b8ebf4fba545475c7aac2f51510d8437dcb8a86aa3230
-  data.tar.gz: 6260815f7523b409fc6af6e4ce15a543f101e8bb85cf196a5dc4c0e6125efc77241e422de8a44f5925d587b83d825e076eb209d24fea04311f57b120b218ef89
+  metadata.gz: 7d3a45bc3b94976166452b9ddf2c411dff01acedd555ba7b124f5eb66c078f5cdab652958a83017e1a253384b874316bf25e523a6eb6f814eb8c04b282063ee5
+  data.tar.gz: e7816087c597af5c4811f7c1155160242268b6beb25c610d93f571e749bc2c92edc7633712eed492d882d23f9576af98637ef46e8857ed4f547608ede6387439

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.13.5
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Add search function to `apple` theme.  
+  [Giles Payne](https://github.com/komakai)
+  [#726](https://github.com/realm/jazzy/issues/726)
+
+* Add option `--[no-]separate-global-declarations` to always create separate
+  documentation pages for top-level declarations as well as classes,
+  structures, enums etc. even if they don't have members. As part of this,
+  improve the main page declaration in all modes.  
+  [Nikolay Volosatov](https://github.com/bamx23)
+  [John Fairhurst](https://github.com/johnfairh)
+
+##### Bug Fixes
+
+* Style fixes for `apple` and `jony` themes to codeblocks inside lists and
+  links.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#818](https://github.com/realm/jazzy/issues/818)
+  [#1177](https://github.com/realm/jazzy/issues/1177)
+
 ## 0.13.4
 
 ##### Breaking

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.13.4)
+    jazzy (0.13.5)
       cocoapods (~> 1.5)
       mustache (~> 1.1)
       open4
@@ -22,10 +22,10 @@ GEM
       tzinfo (~> 1.1)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
-    algoliasearch (1.27.2)
+    algoliasearch (1.27.3)
       httpclient (~> 2.8, >= 2.8.3)
       json (>= 1.5.1)
-    ast (2.4.0)
+    ast (2.4.1)
     atomos (0.1.3)
     bacon (1.2.0)
     claide (1.0.3)
@@ -80,7 +80,7 @@ GEM
       colored2 (~> 3.1)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
-    danger (8.0.0)
+    danger (8.0.2)
       claide (~> 1.0)
       claide-plugins (>= 0.9.2)
       colored2 (~> 3.1)
@@ -101,7 +101,7 @@ GEM
       multipart-post (>= 1.2, < 3)
     faraday-http-cache (2.2.0)
       faraday (>= 0.8)
-    ffi (1.12.2)
+    ffi (1.13.1)
     fourflusher (2.3.1)
     fuzzy_match (2.0.4)
     gh_inspector (1.1.3)
@@ -111,8 +111,8 @@ GEM
     httpclient (2.8.3)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    json (2.3.0)
-    kramdown (2.2.1)
+    json (2.3.1)
+    kramdown (2.3.0)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
@@ -132,9 +132,9 @@ GEM
       faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
     open4 (1.3.4)
-    parallel (1.19.1)
-    parser (2.7.1.3)
-      ast (~> 2.4.0)
+    parallel (1.19.2)
+    parser (2.7.1.4)
+      ast (~> 2.4.1)
     powerpack (0.1.2)
     prettybacon (0.0.2)
       bacon (~> 1.2)
@@ -145,7 +145,7 @@ GEM
     rchardet (1.8.0)
     redcarpet (3.5.0)
     rexml (3.2.4)
-    rouge (3.19.0)
+    rouge (3.20.0)
     rubocop (0.49.0)
       parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)
@@ -156,7 +156,7 @@ GEM
     ruby-macho (1.4.0)
     ruby-progressbar (1.10.1)
     safe_yaml (1.0.5)
-    sassc (2.3.0)
+    sassc (2.4.0)
       ffi (~> 1.9)
     sawyer (0.8.2)
       addressable (>= 2.3.5)
@@ -176,7 +176,7 @@ GEM
       hashdiff (>= 0.4.0, < 2.0.0)
     xcinvoke (0.3.0)
       liferaft (~> 0.0.6)
-    xcodeproj (1.16.0)
+    xcodeproj (1.17.0)
       CFPropertyList (>= 2.3.3, < 4.0)
       atomos (~> 0.1.3)
       claide (>= 1.0.2, < 2.0)

data/README.md

@@ -281,6 +281,13 @@ Note that the `--include` option is applied before the `--exclude` option. For e
 Declarations with a documentation comment containing `:nodoc:` are excluded from the
 documentation.
 
+### Documentation structure
+
+By default Jazzy does not create separate web pages for declarations that do
+not have any members: instead they are nested into some parent page.  Use the
+`--separate-global-declarations` flag to change this and always create pages
+for declarations that can be directly accessed from client code.
+
 ### Choosing the Swift language version
 
 Jazzy normally uses the Swift compiler from the Xcode currently configured by

data/Rakefile

@@ -117,9 +117,14 @@ begin
       'themes/fullwidth/assets/js',
       'themes/jony/assets/js'
     ],
-    'lunr/lunr.min.js' => ['themes/fullwidth/assets/js'],
-    'corejs-typeahead/dist/typeahead.jquery.js' =>
-      ['themes/fullwidth/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']

data/lib/jazzy/config.rb

@@ -437,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_builder.rb

@@ -432,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/gem_version.rb

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

data/lib/jazzy/source_declaration.rb

@@ -11,7 +11,9 @@ module Jazzy
 
     # Give the item its own page or just inline into parent?
     def render_as_page?
-      children.any?
+      children.any? ||
+        (Config.instance.separate_global_declarations &&
+         type.global?)
     end
 
     def swift?
@@ -25,7 +27,8 @@ module Jazzy
     # When referencing this item from its parent category,
     # include the content or just link to it directly?
     def omit_content_from_parent?
-      false
+      Config.instance.separate_global_declarations &&
+        render_as_page?
     end
 
     # Element containing this declaration in the code
@@ -108,6 +111,7 @@ module Jazzy
     attr_accessor :line
     attr_accessor :column
     attr_accessor :usr
+    attr_accessor :type_usr
     attr_accessor :modulename
     attr_accessor :name
     attr_accessor :objc_name
@@ -141,6 +145,15 @@ module Jazzy
       CGI.unescape(url)
     end
 
+    # Base filename (no extension) for the item
+    def docs_filename
+      result = url_name || name
+      # Workaround functions sharing names with
+      # different argument types (f(a:Int) vs. f(a:String))
+      return result unless type.swift_global_function?
+      result + "_#{type_usr}"
+    end
+
     def constrained_extension?
       type.swift_extension? &&
         generic_requirements

data/lib/jazzy/source_declaration/type.rb

@@ -23,6 +23,12 @@ module Jazzy
         @type && @type[:jazzy]
       end
 
+      # kinds that are 'global' and should get their own pages
+      # with --separate-global-declarations
+      def global?
+        @type && @type[:global]
+      end
+
       # name to use for type subdirectory in URLs for back-compatibility
       def url_name
         @type && (@type[:url] || @type[:jazzy])
@@ -118,6 +124,10 @@ module Jazzy
         kind == 'source.lang.swift.decl.typealias'
       end
 
+      def swift_global_function?
+        kind == 'source.lang.swift.decl.function.free'
+      end
+
       def param?
         # SourceKit strangely categorizes initializer parameters as local
         # variables, so both kinds represent a parameter in jazzy.
@@ -180,19 +190,23 @@ module Jazzy
         'sourcekitten.source.lang.objc.decl.category' => {
           jazzy: 'Category',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.class' => {
           jazzy: 'Class',
           dash: 'Class',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.constant' => {
           jazzy: 'Constant',
           dash: 'Constant',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.enum' => {
           jazzy: 'Enumeration',
           url: 'Enum',
           dash: 'Enum',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.enumcase' => {
           jazzy: 'Enumeration Case',
@@ -217,10 +231,12 @@ module Jazzy
         'sourcekitten.source.lang.objc.decl.protocol' => {
           jazzy: 'Protocol',
           dash: 'Protocol',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.typedef' => {
           jazzy: 'Type Definition',
           dash: 'Type',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.mark' => {
           jazzy: 'Mark',
@@ -229,11 +245,13 @@ module Jazzy
         'sourcekitten.source.lang.objc.decl.function' => {
           jazzy: 'Function',
           dash: 'Function',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.struct' => {
           jazzy: 'Structure',
           url: 'Struct',
           dash: 'Struct',
+          global: true,
         }.freeze,
         'sourcekitten.source.lang.objc.decl.field' => {
           jazzy: 'Field',
@@ -300,6 +318,7 @@ module Jazzy
         'source.lang.swift.decl.class' => {
           jazzy: 'Class',
           dash: 'Class',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.constructor' => {
           jazzy: 'Initializer',
@@ -312,6 +331,7 @@ module Jazzy
         'source.lang.swift.decl.var.global' => {
           jazzy: 'Global Variable',
           dash: 'Global',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.enumcase' => {
           jazzy: 'Enumeration Case',
@@ -325,30 +345,37 @@ module Jazzy
           jazzy: 'Enumeration',
           url: 'Enum',
           dash: 'Enum',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension' => {
           jazzy: 'Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.class' => {
           jazzy: 'Class Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.enum' => {
           jazzy: 'Enumeration Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.protocol' => {
           jazzy: 'Protocol Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.extension.struct' => {
           jazzy: 'Structure Extension',
           dash: 'Extension',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.free' => {
           jazzy: 'Function',
           dash: 'Function',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.method.instance' => {
           jazzy: 'Instance Method',
@@ -369,6 +396,7 @@ module Jazzy
         'source.lang.swift.decl.protocol' => {
           jazzy: 'Protocol',
           dash: 'Protocol',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.method.static' => {
           jazzy: 'Static Method',
@@ -382,6 +410,7 @@ module Jazzy
           jazzy: 'Structure',
           url: 'Struct',
           dash: 'Struct',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.function.subscript' => {
           jazzy: 'Subscript',
@@ -391,6 +420,7 @@ module Jazzy
           jazzy: 'Type Alias',
           url: 'Typealias',
           dash: 'Alias',
+          global: true,
         }.freeze,
         'source.lang.swift.decl.generic_type_param' => {
           jazzy: 'Generic Type Parameter',

data/lib/jazzy/sourcekitten.rb

@@ -138,7 +138,7 @@ module Jazzy
     end
 
     def self.sanitize_filename(doc)
-      unsafe_filename = doc.url_name || doc.name
+      unsafe_filename = doc.docs_filename
       sanitzation_enabled = Config.instance.use_safe_filenames
       if sanitzation_enabled && !doc.type.name_controlled_manually?
         return CGI.escape(unsafe_filename).gsub('_', '%5F').tr('%', '_')
@@ -565,6 +565,7 @@ module Jazzy
 
         declaration.file = Pathname(doc['key.filepath']) if doc['key.filepath']
         declaration.usr = doc['key.usr']
+        declaration.type_usr = doc['key.typeusr']
         declaration.modulename = doc['key.modulename']
         declaration.name = documented_name
         declaration.mark = current_mark

data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss

@@ -18,7 +18,7 @@ $content_wrapper_width: 980px;
 $content_top_offset: 70px;
 $content_body_margin: 16px;
 $content_body_left_offset: $sidebar_width + $content_body_margin;
-$header_height: 26px;
+$header_height: 32px;
 $breadcrumb_padding_top: 17px;
 
 $code_font: 0.95em Menlo, monospace;
@@ -104,12 +104,18 @@ p code, li code {
   padding: 2px 4px;
   border-radius: 4px;
 }
+pre > code {
+  padding: 0;
+}
 
 // Links
 
 a {
   color: $link_color;
   text-decoration: none;
+  code {
+    color: inherit;
+  }
 }
 
 // Lists
@@ -152,7 +158,7 @@ header {
   background-color: $bg_color;
   position: fixed;
   width: 100%;
-  z-index: 2;
+  z-index: 3;
   img {
     padding-right: 6px;
     vertical-align: -4px;
@@ -309,6 +315,7 @@ header {
 }
 
 .task-group-section {
+  margin-top: 10px;
   padding-left: 6px;
   border-top: $gray_border;
 }
@@ -529,3 +536,69 @@ html.dash {
     position: static;
   }
 }
+
+// ===========================================================================
+//
+//  Search
+//
+// ===========================================================================
+form[role=search] {
+  float: right;
+
+  input {
+    font: Helvetica, freesans, Arial, sans-serif;
+    margin-top: 6px;
+    font-size: 13px;
+    line-height: 20px;
+    padding: 0px 10px;
+    border: none;
+    border-radius: 1em;
+    .loading & {
+      background: white url(../img/spinner.gif) center right 4px no-repeat;
+    }
+  }
+
+  // Typeahead elements
+
+  .tt-menu {
+    margin: 0;
+    min-width: 300px;
+    background: $white_color;
+    color: #333;
+    border: $gray_border;
+    z-index: 4;
+  }
+
+  .tt-highlight {
+    font-weight: bold;
+  }
+
+  .tt-suggestion {
+    font: Helvetica, freesans, Arial, sans-serif;
+    font-size: 14px;
+    padding: 0 8px;
+    span {
+      display: table-cell;
+      white-space: nowrap;
+    }
+    .doc-parent-name {
+      width: 100%;
+      text-align: right;
+      font-weight: normal;
+      font-size: 0.9em;
+      padding-left: 16px;
+    }
+  }
+
+  .tt-suggestion:hover,
+  .tt-suggestion.tt-cursor {
+    cursor: pointer;
+    background-color: #4183c4;
+    color: #fff;
+  }
+
+  .tt-suggestion:hover .doc-parent-name,
+  .tt-suggestion.tt-cursor .doc-parent-name {
+    color: #fff;
+  }
+}