jazzy 0.13.4 → 0.14.0

data/lib/jazzy/doc.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'date'
 require 'pathname'
 require 'mustache'
@@ -18,7 +20,7 @@ module Jazzy
         date = ENV['JAZZY_FAKE_DATE'] || DateTime.now.strftime('%Y-%m-%d')
         year = date[0..3]
         "© #{year} [#{config.author_name}](#{config.author_url}). " \
-        "All rights reserved. (Last updated: #{date})"
+          "All rights reserved. (Last updated: #{date})"
       )
       Markdown.render_copyright(copyright).chomp
     end

data/lib/jazzy/doc_builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fileutils'
 require 'mustache'
 require 'pathname'
@@ -14,6 +16,7 @@ require 'jazzy/source_declaration'
 require 'jazzy/source_document'
 require 'jazzy/source_module'
 require 'jazzy/sourcekitten'
+require 'jazzy/symbol_graph'
 
 module Jazzy
   # This module handles HTML generation, file writing, asset copying,
@@ -50,8 +53,8 @@ module Jazzy
 
     def self.children_for_doc(doc)
       doc.children
-         .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
-         .flat_map do |child|
+        .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|
@@ -67,11 +70,12 @@ module Jazzy
     # @return [SourceModule] the documented source module
     def self.build(options)
       if options.sourcekitten_sourcefile_configured
-        stdout = '[' + options.sourcekitten_sourcefile.map(&:read)
-                              .join(',') + ']'
+        stdout = "[#{options.sourcekitten_sourcefile.map(&:read).join(',')}]"
       elsif options.podspec_configured
         pod_documenter = PodspecDocumenter.new(options.podspec)
         stdout = pod_documenter.sourcekitten_output(options)
+      elsif options.swift_build_tool == :symbolgraph
+        stdout = SymbolGraph.build(options)
       else
         stdout = Dir.chdir(options.source_directory) do
           arguments = SourceKitten.arguments_from_options(options)
@@ -101,6 +105,7 @@ module Jazzy
     def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
         next unless doc.render_as_page?
+
         # Filepath is relative to documentation root:
         path = output_dir + doc.filepath
         block.call(doc, path)
@@ -129,8 +134,8 @@ module Jazzy
         SearchBuilder.build(source_module, output_dir)
       end
 
-      copy_assets(output_dir)
-      copy_extensions(output_dir)
+      copy_extensions(source_module, output_dir)
+      copy_theme_assets(output_dir)
 
       DocsetBuilder.new(output_dir, source_module).build!
 
@@ -167,7 +172,7 @@ module Jazzy
 
     def self.relative_path_if_inside(path, base_path)
       relative = path.relative_path_from(base_path)
-      if relative.to_path =~ %r{/^..(\/|$)/}
+      if relative.to_path =~ %r{/^..(/|$)/}
         path
       else
         relative
@@ -192,7 +197,10 @@ module Jazzy
 
         lint_report = {
           warnings: warnings.sort_by do |w|
-            [w[:file], w[:line] || 0, w[:symbol], w[:symbol_kind]]
+            [w[:file] || Pathname(''),
+             w[:line] || 0,
+             w[:symbol],
+             w[:symbol_kind]]
           end,
           source_directory: options.source_directory,
         }
@@ -200,7 +208,7 @@ module Jazzy
       end
     end
 
-    def self.copy_assets(destination)
+    def self.copy_theme_assets(destination)
       assets_directory = Config.instance.theme_directory + 'assets'
       FileUtils.cp_r(assets_directory.children, destination)
       Pathname.glob(destination + 'css/**/*.scss').each do |scss|
@@ -211,12 +219,15 @@ module Jazzy
       end
     end
 
-    def self.copy_extensions(destination)
+    def self.copy_extensions(source_module, destination)
+      if source_host = source_module.host&.extension
+        copy_extension(source_host, destination)
+      end
       copy_extension('katex', destination) if Markdown.has_math
     end
 
     def self.copy_extension(name, destination)
-      ext_directory = Pathname(__FILE__).parent + 'extensions/' + name
+      ext_directory = Pathname(__dir__) / 'extensions' / name
       FileUtils.cp_r(ext_directory.children, destination)
     end
 
@@ -225,26 +236,37 @@ module Jazzy
       SourceKitten.autolink_document(html, doc_model)
     end
 
+    # Build Mustache document - common fields between page types
+    def self.new_document(source_module, doc_model)
+      Doc.new.tap do |doc|
+        doc[:custom_head] = Config.instance.custom_head
+        doc[:disable_search] = Config.instance.disable_search
+        doc[:doc_coverage] = source_module.doc_coverage unless
+          Config.instance.hide_documentation_coverage
+        doc[:structure] = source_module.doc_structure
+        doc[:module_name] = source_module.name
+        doc[:author_name] = source_module.author_name
+        if source_host = source_module.host
+          doc[:source_host_name] = source_host.name
+          doc[:source_host_url] = source_host.url
+          doc[:source_host_image] = source_host.image
+          doc[:source_host_item_url] = source_host.item_url(doc_model)
+          doc[:github_url] = doc[:source_host_url]
+          doc[:github_token_url] = doc[:source_host_item_url]
+        end
+        doc[:dash_url] = source_module.dash_url
+      end
+    end
+
     # Build Mustache document from a markdown source file
-    # @param [Config] options Build options
+    # @param [SourceModule] module-wide settings
     # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
     # @param [String] path_to_root
-    # @param [Array] doc_structure doc structure comprised of section names and
-    #        child names and URLs. @see doc_structure_for_docs
     def self.document_markdown(source_module, doc_model, path_to_root)
-      doc = Doc.new # Mustache model instance
+      doc = new_document(source_module, doc_model)
       name = doc_model.name == 'index' ? source_module.name : doc_model.name
       doc[:name] = name
       doc[:overview] = render(doc_model, doc_model.content(source_module))
-      doc[:custom_head] = Config.instance.custom_head
-      doc[:disable_search] = Config.instance.disable_search
-      doc[:doc_coverage] = source_module.doc_coverage unless
-        Config.instance.hide_documentation_coverage
-      doc[:structure] = source_module.doc_structure
-      doc[:module_name] = source_module.name
-      doc[:author_name] = source_module.author_name
-      doc[:github_url] = source_module.github_url
-      doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:hide_name] = true
       doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
@@ -318,30 +340,6 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
 
-    def self.should_link_to_github(file)
-      return unless file
-      file = file.realpath.to_path
-      source_directory = Config.instance.source_directory.to_path
-      file.start_with?(source_directory)
-    end
-
-    # Construct Github token URL
-    # @param [Hash] item Parsed doc child item
-    # @param [Config] options Build options
-    def self.gh_token_url(item, source_module)
-      return unless github_prefix = source_module.github_file_prefix
-      return unless should_link_to_github(item.file)
-      gh_line = if item.start_line && (item.start_line != item.end_line)
-                  "#L#{item.start_line}-L#{item.end_line}"
-                else
-                  "#L#{item.line}"
-                end
-      relative_file_path = item.file.realpath.relative_path_from(
-        source_module.root_path,
-      )
-      "#{github_prefix}/#{relative_file_path}#{gh_line}"
-    end
-
     # Build mustache item for a top-level doc
     # @param [Hash] item Parsed doc child item
     # @param [Config] options Build options
@@ -349,27 +347,29 @@ module Jazzy
     def self.render_item(item, source_module)
       # Combine abstract and discussion into abstract
       abstract = (item.abstract || '') + (item.discussion || '')
+      source_host_item_url = source_module.host&.item_url(item)
       {
-        name:                       item.name,
-        name_html:                  item.name.gsub(':', ':<wbr>'),
-        abstract:                   abstract,
-        declaration:                item.display_declaration,
-        language:                   item.display_language,
+        name: item.name,
+        name_html: item.name.gsub(':', ':<wbr>'),
+        abstract: abstract,
+        declaration: item.display_declaration,
+        language: item.display_language,
         other_language_declaration: item.display_other_language_declaration,
-        usr:                        item.usr,
-        dash_type:                  item.type.dash_type,
-        github_token_url:           gh_token_url(item, source_module),
-        default_impl_abstract:      item.default_impl_abstract,
-        from_protocol_extension:    item.from_protocol_extension,
-        return:                     item.return,
-        parameters:                 (item.parameters if item.parameters.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?,
+        usr: item.usr,
+        dash_type: item.type.dash_type,
+        source_host_item_url: source_host_item_url,
+        github_token_url: source_host_item_url,
+        default_impl_abstract: item.default_impl_abstract,
+        from_protocol_extension: item.from_protocol_extension,
+        return: item.return,
+        parameters: (item.parameters if item.parameters.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
@@ -406,12 +406,10 @@ module Jazzy
     end
 
     # rubocop:disable Metrics/MethodLength
-    # Build Mustache document from single parsed doc
-    # @param [Config] options Build options
+    # Build Mustache document from single parsed decl
+    # @param [SourceModule] module-wide settings
     # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
     # @param [String] path_to_root
-    # @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.markdown?
         return document_markdown(source_module, doc_model, path_to_root)
@@ -423,22 +421,18 @@ module Jazzy
         overview = render(doc_model, alternative_abstract) + overview
       end
 
-      doc = Doc.new # Mustache model instance
-      doc[:custom_head] = Config.instance.custom_head
-      doc[:disable_search] = Config.instance.disable_search
-      doc[:doc_coverage] = source_module.doc_coverage unless
-        Config.instance.hide_documentation_coverage
+      doc = new_document(source_module, doc_model)
       doc[:name] = doc_model.name
       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[:structure] = source_module.doc_structure
+      doc[:parameters] = doc_model.parameters
+      doc[:return] = doc_model.return
       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[: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

data/lib/jazzy/docset_builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mustache'
 require 'sqlite3'
 
@@ -89,7 +91,7 @@ module Jazzy
         (output_dir + "#{source_module.name}.xml").open('w') do |xml|
           url = URI.join(config.root_url, "docsets/#{source_module.name}.tgz")
           xml << "<entry><version>#{config.version}</version><url>#{url}" \
-                 "</url></entry>\n"
+            "</url></entry>\n"
         end
       end
     end

data/lib/jazzy/documentation_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'pathname'
 
 require 'jazzy/jazzy_markdown'
@@ -12,19 +14,21 @@ module Jazzy
         SourceDocument.new.tap do |sd|
           sd.name = File.basename(file_path, '.md')
           sd.overview = overview Pathname(file_path)
-          sd.usr = 'documentation.' + sd.name
+          sd.usr = "documentation.#{sd.name}"
         end
       end
     end
 
     def self.overview(file_path)
-      return '' unless file_path && file_path.exist?
+      return '' unless file_path&.exist?
+
       file_path.read
     end
 
     def self.documentation_entries
       return [] unless
         config.documentation_glob_configured && config.documentation_glob
+
       config.documentation_glob.select { |e| File.file? e }
     end
   end

data/lib/jazzy/executable.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 module Jazzy
   module Executable
     class IO < Array
       def initialize(io = nil)
+        super()
         @io = io
       end
 

data/lib/jazzy/extensions/bitbucket/img/bitbucket.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg fill="none" version="1.1" viewBox="0 0 24 21.58" xmlns="http://www.w3.org/2000/svg">
+ <path d="m22.95 7.2332h-7.1932l-1.1989 7.0734h-4.9953l-5.8745 6.9934s0.27972 0.2398 0.67935 0.2398h15.665c0.3597 0 0.6794-0.2797 0.7593-0.6394z" fill="url(#paint0_linear)"/>
+ <path d="m0.77041 0c-0.47956 0-0.83918 0.43959-0.75926 0.87918l3.237 19.822c0.03996 0.2398 0.15986 0.4796 0.35968 0.6394 0 0 0.27972 0.2398 0.67935 0.2398l6.0743-7.2732h-0.8392l-1.3188-7.0734h14.746l1.039-6.3541c0.08-0.47955-0.2797-0.87918-0.7593-0.87918z" fill="#fff"/>
+ <defs>
+  <linearGradient id="paint0_linear" x1="27.898" x2="16.618" y1="15.387" y2="23.023" gradientTransform="translate(-4 -5)" gradientUnits="userSpaceOnUse">
+   <stop stop-color="#fff" stop-opacity=".4" offset=".071833"/>
+   <stop stop-color="#fff" offset="1"/>
+  </linearGradient>
+ </defs>
+</svg>

data/lib/jazzy/extensions/gitlab/img/gitlab.svg

@@ -0,0 +1,23 @@
+<svg
+   xmlns="http://www.w3.org/2000/svg"
+   height="313.44601"
+   width="338.96616"
+   xml:space="preserve"
+   viewBox="0 0 338.96616 313.44601"
+   y="0px"
+   x="0px"
+   version="1.1">
+<style
+   id="style10"
+   type="text/css">
+	.st2{fill:#FFFFFF;}
+</style>
+<g
+   transform="translate(-123.54995,-122.776)"
+   id="logo_art">
+	<path
+   id="path12"
+   d="m 461.514,298.355 -18.049,-55.587 c 0.008,0.025 0.011,0.051 0.019,0.076 -0.009,-0.029 -0.014,-0.058 -0.022,-0.087 -10e-4,-0.002 -10e-4,-0.003 -10e-4,-0.005 0,-0.001 0,-0.002 0,-0.002 l -35.83,-110.31 c -1.96,-5.811 -7.353,-9.711 -13.536,-9.663 -6.201,0.032 -11.446,3.857 -13.364,9.748 L 346.721,237.23 H 239.408 L 205.334,132.518 c -1.916,-5.886 -7.162,-9.71 -13.362,-9.742 -0.025,0 -0.049,0 -0.075,0 -6.105,0 -11.509,3.876 -13.49,9.752 l -35.732,110.211 -0.005,0.014 c 0,0.001 0,0.002 0,0.003 -0.009,0.028 -0.013,0.056 -0.022,0.084 0.008,-0.025 0.011,-0.051 0.019,-0.076 l -18.115,55.591 c -2.725,8.392 0.232,17.512 7.36,22.697 L 288.328,434.7 c 0.023,0.017 0.049,0.027 0.072,0.044 0.067,0.048 0.132,0.097 0.2,0.142 -0.064,-0.043 -0.124,-0.09 -0.187,-0.134 0,0 0,-0.001 -0.001,-0.001 0.01,0.008 0.022,0.013 0.033,0.02 0.009,0.006 0.018,0.01 0.027,0.016 0.001,0.001 0.002,0.002 0.004,0.003 0.242,0.168 0.493,0.322 0.753,0.463 0.036,0.02 0.068,0.045 0.104,0.064 10e-4,0 10e-4,10e-4 0.002,10e-4 0.022,0.011 0.042,0.025 0.064,0.036 0.017,0.008 0.035,0.013 0.051,0.021 0.012,0.006 0.025,0.01 0.037,0.015 0.029,0.014 0.061,0.023 0.09,0.038 0.136,0.065 0.279,0.118 0.419,0.175 0.131,0.054 0.258,0.117 0.392,0.164 0.006,0.002 0.011,0.005 0.017,0.007 0.022,0.008 0.042,0.019 0.065,0.027 0.028,0.01 0.055,0.021 0.083,0.03 0.011,0.003 0.022,0.005 0.033,0.008 0.035,0.011 0.073,0.016 0.108,0.026 0.013,0.004 0.028,0.006 0.042,0.01 0.188,0.057 0.383,0.098 0.577,0.141 0.076,0.017 0.149,0.041 0.226,0.055 0.011,0.002 0.021,0.006 0.033,0.008 0.025,0.005 0.048,0.014 0.074,0.018 0.041,0.007 0.081,0.02 0.123,0.026 0.033,0.005 0.067,0.003 0.1,0.008 0.006,0.001 0.011,0 0.017,0.001 0.002,0 0.003,0 0.005,0 0.369,0.053 0.743,0.09 1.124,0.09 0.002,0 0.004,0 0.007,0 v 0 c 0.001,0 0.002,0 0.002,0 0,0 10e-4,0 10e-4,0 0.001,0 0.002,0 0.003,0 0.382,0 0.756,-0.037 1.126,-0.09 10e-4,0 0.003,0 0.004,0 0.006,-0.001 0.012,0 0.018,-0.001 0.033,-0.005 0.068,-0.003 0.101,-0.008 0.042,-0.007 0.082,-0.019 0.124,-0.026 0.025,-0.004 0.048,-0.013 0.073,-0.018 0.011,-0.002 0.021,-0.006 0.032,-0.008 0.078,-0.015 0.153,-0.039 0.231,-0.056 0.191,-0.042 0.383,-0.083 0.57,-0.139 0.013,-0.004 0.026,-0.005 0.039,-0.009 0.037,-0.011 0.075,-0.016 0.112,-0.027 0.011,-0.004 0.023,-0.005 0.034,-0.008 0.029,-0.009 0.057,-0.021 0.085,-0.031 0.022,-0.008 0.042,-0.019 0.064,-0.027 0.006,-0.002 0.011,-0.005 0.017,-0.007 0.142,-0.05 0.276,-0.116 0.415,-0.173 0.129,-0.054 0.261,-0.102 0.387,-0.162 0.031,-0.015 0.064,-0.024 0.094,-0.039 0.012,-0.006 0.026,-0.01 0.038,-0.016 0.017,-0.008 0.035,-0.013 0.052,-0.022 0.023,-0.012 0.045,-0.026 0.067,-0.037 0,0 10e-4,0 10e-4,-10e-4 0.037,-0.019 0.07,-0.046 0.107,-0.066 0.258,-0.14 0.508,-0.293 0.749,-0.46 0.019,-0.013 0.041,-0.023 0.061,-0.037 0.005,-0.004 0.011,-0.006 0.016,-0.01 0.023,-0.017 0.05,-0.028 0.073,-0.045 l 156.44,-113.65 c 7.124,-5.182 10.081,-14.302 7.356,-22.694 z m -67.32,-155.581 30.68,94.456 h -61.36 z m 25.307,110.428 -12.519,16.041 -92.334,118.307 43.677,-134.348 z M 285.428,430.707 c 0,0 0,0 0,0 0.008,0.024 0.021,0.046 0.029,0.071 -0.008,-0.025 -0.021,-0.047 -0.029,-0.071 z M 271.42,387.558 166.624,253.202 v 0 h 61.18 z m -79.545,-244.785 30.737,94.457 h -61.36 z m -50.571,165.36 c -1.516,-1.103 -2.144,-3.05 -1.563,-4.838 l 13.466,-41.325 98.67,126.502 z m 146.749,126.356 c -0.031,-0.025 -0.061,-0.052 -0.091,-0.078 -0.006,-0.005 -0.012,-0.012 -0.019,-0.017 -0.06,-0.05 -0.119,-0.101 -0.177,-0.153 -0.114,-0.099 -0.226,-0.2 -0.333,-0.306 0.009,0.008 0.019,0.015 0.028,0.023 0.012,0.011 0.025,0.02 0.037,0.031 0.229,0.219 0.47,0.425 0.722,0.615 0.003,0.002 0.005,0.005 0.008,0.007 0.012,0.009 0.022,0.02 0.034,0.03 -0.069,-0.05 -0.141,-0.098 -0.209,-0.152 z m 4.975,-32.097 -25.665,-79.059 -22.766,-70.131 h 96.933 z m 5.253,31.849 c -0.06,0.052 -0.118,0.104 -0.179,0.154 -0.007,0.006 -0.014,0.013 -0.021,0.019 -0.031,0.025 -0.06,0.052 -0.09,0.077 -0.066,0.053 -0.138,0.101 -0.207,0.152 0.012,-0.009 0.022,-0.021 0.035,-0.029 0.002,-0.002 0.004,-0.004 0.006,-0.006 0.252,-0.19 0.492,-0.394 0.719,-0.613 0.009,-0.009 0.02,-0.016 0.029,-0.024 0.012,-0.011 0.025,-0.02 0.036,-0.031 -0.106,0.103 -0.217,0.203 -0.328,0.301 z M 444.766,308.13 334.209,388.447 432.912,261.98 l 13.412,41.307 c 0.582,1.796 -0.045,3.743 -1.558,4.843 z"
+   class="st2" />
+</g>
+</svg>