jazzy 0.9.3 → 0.9.5

data/lib/jazzy/doc_builder.rb

@@ -10,7 +10,6 @@ require 'jazzy/documentation_generator'
 require 'jazzy/search_builder'
 require 'jazzy/jazzy_markdown'
 require 'jazzy/podspec_documenter'
-require 'jazzy/readme_generator'
 require 'jazzy/source_declaration'
 require 'jazzy/source_document'
 require 'jazzy/source_module'
@@ -95,7 +94,7 @@ module Jazzy
 
     def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
-        next unless doc.render?
+        next unless doc.render_as_page?
         # Assuming URL is relative to documentation root:
         path = output_dir + (doc.url || "#{doc.name}.html")
         block.call(doc, path)
@@ -332,6 +331,7 @@ module Jazzy
     # Build mustache item for a top-level doc
     # @param [Hash] item Parsed doc child item
     # @param [Config] options Build options
+    # rubocop:disable Metrics/MethodLength
     def self.render_item(item, source_module)
       # Combine abstract and discussion into abstract
       abstract = (item.abstract || '') + (item.discussion || '')
@@ -347,11 +347,16 @@ module Jazzy
         from_protocol_extension:    item.from_protocol_extension,
         return:                     item.return,
         parameters:                 (item.parameters if item.parameters.any?),
-        url:                        (item.url if item.children.any?),
+        url:                        (item.url if item.render_as_page?),
         start_line:                 item.start_line,
         end_line:                   item.end_line,
+        direct_link:                item.omit_content_from_parent?,
+        deprecation_message:        item.deprecation_message,
+        unavailable_message:        item.unavailable_message,
+        usage_discouraged:          item.usage_discouraged?,
       }
     end
+    # rubocop:enable Metrics/MethodLength
 
     def self.make_task(mark, uid, items)
       {
@@ -391,7 +396,7 @@ module Jazzy
     # @param [Array] doc_structure doc structure comprised of section names and
     #        child names and URLs. @see doc_structure_for_docs
     def self.document(source_module, doc_model, path_to_root)
-      if doc_model.type.kind == 'document.markdown'
+      if doc_model.type.markdown?
         return document_markdown(source_module, doc_model, path_to_root)
       end
 
@@ -418,6 +423,9 @@ module Jazzy
       doc[:github_url] = source_module.github_url
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
+      doc[:deprecation_message] = doc_model.deprecation_message
+      doc[:unavailable_message] = doc_model.unavailable_message
+      doc[:usage_discouraged] = doc_model.usage_discouraged?
       doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
     end
     # rubocop:enable Metrics/MethodLength

data/lib/jazzy/documentation_generator.rb

@@ -11,15 +11,8 @@ module Jazzy
       documentation_entries.map do |file_path|
         SourceDocument.new.tap do |sd|
           sd.name = File.basename(file_path, '.md')
-          sd.url = sd.name.downcase.strip
-                     .tr(' ', '-').gsub(/[^\w-]/, '') + '.html'
-          sd.type = SourceDeclaration::Type.new 'document.markdown'
-          sd.children = []
           sd.overview = overview Pathname(file_path)
           sd.usr = 'documentation.' + sd.name
-          sd.abstract = ''
-          sd.return = ''
-          sd.parameters = []
         end
       end
     end

data/lib/jazzy/gem_version.rb

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

data/lib/jazzy/podspec_documenter.rb

@@ -27,8 +27,8 @@ module Jazzy
 
           targets.map do |t|
             args = %W[doc --module-name #{podspec.module_name} -- -target #{t}]
-            swift_version = (config.swift_version || '4')[0] + '.0'
-            args << "SWIFT_VERSION=\"#{swift_version}\""
+            swift_version = compiler_swift_version(config.swift_version)
+            args << "SWIFT_VERSION=#{swift_version}"
             SourceKitten.run_sourcekitten(args)
           end
         end
@@ -97,6 +97,23 @@ module Jazzy
 
     private_class_method :github_file_prefix
 
+    # Latest valid value for SWIFT_VERSION.
+    LATEST_SWIFT_VERSION = '4.2'.freeze
+
+    # All valid values for SWIFT_VERSION that are longer
+    # than a major version number.  Ordered ascending.
+    LONG_SWIFT_VERSIONS = ['4.2'].freeze
+
+    # Go from a full Swift version like 4.2.1 to
+    # something valid for SWIFT_VERSION.
+    def compiler_swift_version(user_version)
+      return LATEST_SWIFT_VERSION unless user_version
+
+      LONG_SWIFT_VERSIONS.select do |version|
+        user_version.start_with?(version)
+      end.last || "#{user_version[0]}.0"
+    end
+
     # @!group SourceKitten output helper methods
 
     def pod_path

data/lib/jazzy/source_declaration.rb

@@ -8,12 +8,15 @@ module Jazzy
     # static type of declared element (e.g. String.Type -> ())
     attr_accessor :typename
 
-    def type?(type_kind)
-      respond_to?(:type) && type.kind == type_kind
+    # Give the item its own page or just inline into parent?
+    def render_as_page?
+      children.any?
     end
 
-    def render?
-      type?('document.markdown') || children.count != 0
+    # When referencing this item from its parent category,
+    # include the content or just link to it directly?
+    def omit_content_from_parent?
+      false
     end
 
     # Element containing this declaration in the code
@@ -99,6 +102,14 @@ module Jazzy
     attr_accessor :end_line
     attr_accessor :nav_order
     attr_accessor :url_name
+    attr_accessor :deprecated
+    attr_accessor :deprecation_message
+    attr_accessor :unavailable
+    attr_accessor :unavailable_message
+
+    def usage_discouraged?
+      unavailable || deprecated
+    end
 
     def alternative_abstract
       if file = alternative_abstract_file

data/lib/jazzy/source_declaration/type.rb

@@ -129,6 +129,16 @@ module Jazzy
         Type.new('Overview')
       end
 
+      MARKDOWN_KIND = 'document.markdown'.freeze
+
+      def self.markdown
+        Type.new(MARKDOWN_KIND)
+      end
+
+      def markdown?
+        kind == MARKDOWN_KIND
+      end
+
       def hash
         kind.hash
       end
@@ -140,7 +150,7 @@ module Jazzy
 
       TYPES = {
         # Markdown
-        'document.markdown' => {
+        MARKDOWN_KIND => {
           jazzy: 'Guide',
           dash: 'Guide',
         }.freeze,

data/lib/jazzy/source_document.rb

@@ -3,19 +3,35 @@ require 'pathname'
 require 'jazzy/jazzy_markdown'
 
 module Jazzy
+  # Standalone markdown docs including index.html
   class SourceDocument < SourceDeclaration
     attr_accessor :overview
     attr_accessor :readme_path
 
+    def initialize
+      super
+      self.children = []
+      self.parameters = []
+      self.abstract = ''
+      self.type = SourceDeclaration::Type.markdown
+      self.mark = SourceMark.new
+    end
+
     def self.make_index(readme_path)
       SourceDocument.new.tap do |sd|
         sd.name = 'index'
-        sd.children = []
-        sd.type = SourceDeclaration::Type.new 'document.markdown'
         sd.readme_path = readme_path
       end
     end
 
+    def render_as_page?
+      true
+    end
+
+    def omit_content_from_parent?
+      true
+    end
+
     def config
       Config.instance
     end

data/lib/jazzy/sourcekitten.rb

@@ -322,6 +322,8 @@ module Jazzy
           Highlighter.highlight(make_swift_declaration(doc, declaration))
       end
 
+      make_deprecation_info(doc, declaration)
+
       unless doc['key.doc.full_as_xml']
         return process_undocumented_token(doc, declaration)
       end
@@ -335,10 +337,23 @@ module Jazzy
       @stats.add_documented
     end
 
+    def self.make_deprecation_info(doc, declaration)
+      if declaration.deprecated
+        declaration.deprecation_message =
+          Markdown.render(doc['key.deprecation_message'] || '')
+      end
+      if declaration.unavailable
+        declaration.unavailable_message =
+          Markdown.render(doc['key.unavailable_message'] || '')
+      end
+    end
+
     # Strip tags and convert entities
     def self.xml_to_text(xml)
       document = REXML::Document.new(xml)
       REXML::XPath.match(document.root, '//text()').map(&:value).join
+    rescue
+      ''
     end
 
     # Regexp to match an @attribute.  Complex to handle @available().
@@ -372,10 +387,11 @@ module Jazzy
     end
 
     def self.prefer_parsed_decl?(parsed, annotated)
-      parsed &&
-        (annotated.include?(' = default') || # SR-2608
-         parsed.match('@autoclosure|@escaping') || # SR-6321
-         parsed.include?("\n"))
+      annotated.empty? ||
+        parsed &&
+          (annotated.include?(' = default') || # SR-2608
+           parsed.match('@autoclosure|@escaping') || # SR-6321
+           parsed.include?("\n"))
     end
 
     # Replace the fully qualified name of a type with its base name
@@ -479,6 +495,8 @@ module Jazzy
         declaration.column = doc['key.doc.column']
         declaration.start_line = doc['key.parsed_scope.start']
         declaration.end_line = doc['key.parsed_scope.end']
+        declaration.deprecated = doc['key.always_deprecated']
+        declaration.unavailable = doc['key.always_unavailable']
 
         next unless make_doc_info(doc, declaration)
         make_substructure(doc, declaration)
@@ -739,28 +757,34 @@ module Jazzy
       end
     end
 
+    AUTOLINK_TEXT_FIELDS = %w[return
+                              abstract
+                              unavailable_message
+                              deprecation_message].freeze
+
+    AUTOLINK_HIGHLIGHT_FIELDS = %w[declaration
+                                   other_language_declaration].freeze
+
     def self.autolink(docs, root_decls)
       @autolink_root_decls = root_decls
       docs.each do |doc|
         doc.children = autolink(doc.children, root_decls)
 
-        doc.return = autolink_text(doc.return, doc, root_decls) if doc.return
-        doc.abstract = autolink_text(doc.abstract, doc, root_decls)
-        (doc.parameters || []).each do |param|
-          param[:discussion] =
-            autolink_text(param[:discussion], doc, root_decls)
+        AUTOLINK_TEXT_FIELDS.each do |field|
+          if text = doc.send(field)
+            doc.send(field + '=', autolink_text(text, doc, root_decls))
+          end
         end
 
-        if doc.declaration
-          doc.declaration = autolink_text(
-            doc.declaration, doc, root_decls, true
-          )
+        AUTOLINK_HIGHLIGHT_FIELDS.each do |field|
+          if text = doc.send(field)
+            doc.send(field + '=', autolink_text(text, doc, root_decls, true))
+          end
         end
 
-        if doc.other_language_declaration
-          doc.other_language_declaration = autolink_text(
-            doc.other_language_declaration, doc, root_decls, true
-          )
+        (doc.parameters || []).each do |param|
+          param[:discussion] =
+            autolink_text(param[:discussion], doc, root_decls)
         end
       end
     end

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

@@ -240,7 +240,7 @@ header {
   margin-left: $content_body_left_offset;
   position: absolute;
   overflow: hidden;
-  padding-bottom: 60px;
+  padding-bottom: 20px;
   top: $content_top_offset;
   width: $content_wrapper_width - $content_body_left_offset;
   p, a, code, em, ul, table, blockquote {
@@ -333,11 +333,14 @@ header {
     background-color: transparent;
     padding: 0;
   }
-  .token {
+  .token, .direct-link {
     padding-left: 3px;
     margin-left: 15px;
     font-size: 11.9px;
   }
+  .discouraged {
+    text-decoration: line-through;
+  }
   .declaration-note {
     font-size: .85em;
     color: rgba(128,128,128,1);
@@ -412,7 +415,7 @@ header {
   }
 }
 
-.aside-warning {
+.aside-warning, .aside-deprecated, .aside-unavailable {
   border-left: $aside_warning_border;
   .aside-title {
     color: $aside_warning_color;
@@ -446,8 +449,9 @@ header {
 }
 
 #footer {
-  position: absolute;
-  bottom: 10px;
+  position: relative;
+  top: 10px;
+  bottom: 0px;
   margin-left: 25px;
   p {
     margin: 0;

data/lib/jazzy/themes/apple/templates/deprecation.mustache

@@ -0,0 +1,12 @@
+{{#deprecation_message}}
+<div class="aside aside-deprecated">
+  <p class="aside-title">Deprecated</p>
+  {{{deprecation_message}}}
+</div>
+{{/deprecation_message}}
+{{#unavailable_message}}
+<div class="aside aside-unavailable">
+  <p class="aside-title">Unavailable</p>
+  {{{unavailable_message}}}
+</div>
+{{/unavailable_message}}

data/lib/jazzy/themes/apple/templates/doc.mustache

@@ -28,6 +28,7 @@
         <section>
           <section class="section">
             {{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
+            {{> deprecation}}
             {{#declaration}}
               <div class="declaration">
                 <div class="language">

data/lib/jazzy/themes/apple/templates/task.mustache

@@ -15,7 +15,17 @@
         <code>
         <a name="/{{usr}}"></a>
         <a name="//apple_ref/{{language_stub}}/{{dash_type}}/{{name}}" class="dashAnchor"></a>
+        {{#direct_link}}
+        <a class="direct-link" href="{{url}}">{{name}}</a>
+        </code>
+        {{/direct_link}}
+        {{^direct_link}}
+        {{^usage_discouraged}}
         <a class="token" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
+        {{#usage_discouraged}}
+        <a class="token discouraged" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
         </code>
         {{#default_impl_abstract}}
           <span class="declaration-note">
@@ -32,6 +42,7 @@
         <div class="pointer-container"></div>
         <section class="section">
           <div class="pointer"></div>
+          {{> deprecation}}
           {{#abstract}}
           <div class="abstract">
             {{{abstract}}}
@@ -85,6 +96,7 @@
           </div>
           {{/github_token_url}}
         </section>
+        {{/direct_link}}
       </div>
     </li>
     {{/items}}

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

@@ -154,8 +154,14 @@ a {
     outline: 0;
     text-decoration: underline;
   }
-}
 
+  &.discouraged {
+    text-decoration: line-through;
+    &:hover, &:focus {
+      text-decoration: underline line-through;
+    }
+  }
+}
 
 // ----- Tables
 
@@ -404,7 +410,7 @@ pre code {
     }
   }
 
-  .token {
+  .token, .direct-link {
     padding-left: 3px;
     margin-left: 0px;
     font-size: 1rem;
@@ -479,7 +485,7 @@ pre code {
   }
 }
 
-.aside-warning {
+.aside-warning, .aside-deprecated, .aside-unavailable {
   border-left: $aside_warning_border;
   .aside-title {
     color: $aside_warning_color;
@@ -612,4 +618,4 @@ form[role=search] {
   .tt-suggestion.tt-cursor .doc-parent-name {
     color: #fff;
   }
-}
+}