RubyGems - jazzy - Versions diffs - 0.1.4 → 0.1.5 - Mend

jazzy 0.1.4 → 0.1.5

Files changed (81) hide show

data/lib/jazzy/assets/js/jazzy.js CHANGED Viewed

@@ -1,3 +1,13 @@
+window.jazzy = {'docset': false}
+if (typeof window.dash != 'undefined') {
+  document.documentElement.className += ' dash'
+  window.jazzy.docset = true
+}
+if (navigator.userAgent.match(/xcode/i)) {
+  document.documentElement.className += ' xcode'
+  window.jazzy.docset = true
+}
 // On doc load, toggle the URL hash discussion if present
 $(document).ready(function() {
   if (!window.jazzy.docset) {
@@ -6,8 +16,8 @@ $(document).ready(function() {
   }
 });
-// On x-instance-method click, toggle its discussion and animate token.marginLeft
-$(".x-instance-method").click(function() {
+// On token click, toggle its discussion and animate token.marginLeft
+$(".token").click(function() {
   if (window.jazzy.docset) {
     return;
   }

data/lib/jazzy/config.rb CHANGED Viewed

@@ -107,7 +107,7 @@ module Jazzy
         end
         opt.on('-s', '--sourcekitten-sourcefile FILEPATH',
-               'XML doc file generated from sourcekitten to parse') do |s|
+               'File generated from sourcekitten output to parse') do |s|
           config.sourcekitten_sourcefile = Pathname(s)
         end
@@ -159,6 +159,11 @@ module Jazzy
           config.source_directory = Pathname(source_directory)
         end
+        opt.on('--readme FILEPATH',
+               'The path to a markdown README file') do |readme|
+          config.readme_path = Pathname(readme)
+        end
         opt.on('-v', '--version', 'Print version number') do
           puts 'jazzy version: ' + Jazzy::VERSION
           exit

data/lib/jazzy/doc.mustache CHANGED Viewed

@@ -5,54 +5,28 @@
     <link rel="stylesheet" type="text/css" href="{{path_to_root}}css/jazzy.css" />
     <link rel="stylesheet" type="text/css" href="{{path_to_root}}css/highlight.css" />
     <meta charset='utf-8'>
-    <script type="text/javascript">
-    window.jazzy = {'docset': false}
-    if (typeof window.dash != 'undefined') {
-      document.documentElement.className += ' dash'
-      window.jazzy.docset = true
-    }
-    if (navigator.userAgent.match(/xcode/i)) {
-      document.documentElement.className += ' xcode'
-      window.jazzy.docset = true
-    }
-    </script>
     <script src="{{path_to_root}}js/jquery.min.js" defer></script>
     <script src="{{path_to_root}}js/jazzy.js" defer></script>
   </head>
-  <body id="reference" class="Swift">
+  <body>
     {{#dash_type}}
     <a name="//apple_ref/swift/{{dash_type}}/{{name}}" class="dashAnchor"></a>
     {{/dash_type}}
     <a title="{{name}} {{kind}} Reference"></a>
-    <header>
-      <div class="content-wrapper">
-        <p class="header-text"><a href="{{path_to_root}}index.html">{{module_name}} Docs</a> ({{doc_coverage}}% documented)</p>
-        {{#github_url}}
-        <p id="header-links"><a href="{{github_url}}"><img id="header-icon" src="{{path_to_root}}img/gh.png" height="16px" width="16px" />View on GitHub</a></p>
-        {{/github_url}}
-        {{#dash_url}}
-        <p id="header-links"><a href="{{dash_url}}"><img id="header-icon" src="{{path_to_root}}img/dash.png" height="16px" width="16px" />Install in Dash</a></p>
-        {{/dash_url}}
-      </div>
-    </header>
-    <section id="valence">
-      <div class="content-wrapper">
-        <p id="hierarchial_navigation">
-        <a href="{{path_to_root}}index.html" id="design_resources_link">{{module_name}} Reference</a>
-        <img id="carat" src="{{path_to_root}}img/carat.png" height="10px" width="6px" />
+    {{> jazzy/partials/header}}
+    <div class="content-wrapper">
+      <p id="breadcrumbs">
+        <a href="{{path_to_root}}index.html">{{module_name}} Reference</a>
+        <img id="carat" src="{{path_to_root}}img/carat.png" />
         {{name}} {{kind}} Reference
-        </p>
-      </div>
-    </section>
+      </p>
+    </div>
     <div class="content-wrapper">
       {{> jazzy/partials/nav}}
-      <div class="pixel-line"></div>
-      <div class="rubber-band-gap"></div>
-      <article class="chapter">
-      <a name="/{{usr}}"></a>
-        <h1 class="chapter-name">{{name}}</h1>
+      <article class="main-content">
         <section>
           <section class="section">
+            {{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
             {{{overview}}}
           </section>
           {{> jazzy/partials/tasks}}

data/lib/jazzy/doc_builder.rb CHANGED Viewed

@@ -18,8 +18,6 @@ module Jazzy
   # This module handles HTML generation, file writing, asset copying,
   # and generally building docs given sourcekitten output
   module DocBuilder
-    DEVELOPER_DIR = `xcode-select -p`.chomp
     # mkdir -p output directory and clean if option is set
     def self.prepare_output_dir(output_dir, clean)
       FileUtils.rm_r output_dir if clean && output_dir.directory?
@@ -30,16 +28,14 @@ module Jazzy
     # @return [Array] doc structure comprised of
     #                     section names & child names & URLs
     def self.doc_structure_for_docs(docs)
-      structure = []
-      docs.each do |doc|
-        structure << {
+      docs.map do |doc|
+        {
           section: doc.name,
           children: doc.children.sort_by(&:name).map do |child|
             { name: child.name, url: child.url }
           end,
         }
       end
-      structure
     end
     # Build documentation from the given options
@@ -192,11 +188,14 @@ module Jazzy
       doc[:github_url] = source_module.github_url.to_s
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
+      doc[:hide_name] = true
       doc.render
     end
     def self.should_link_to_github(file)
-      !file.start_with?(DEVELOPER_DIR) if file
+      developer_directory = SourceKitten.xcode_developer_directory
+      return unless developer_directory && file
+      !file.start_with?(developer_directory.realpath.to_s)
     end
     # Construct Github token URL
@@ -205,7 +204,11 @@ module Jazzy
     def self.gh_token_url(item, source_module)
       if source_module.github_file_prefix && should_link_to_github(item.file)
         relative_file_path = item.file.gsub(`pwd`.strip, '')
-        gh_line = "#L#{item.line}"
+        if item.start_line && (item.start_line != item.end_line)
+          gh_line = "#L#{item.start_line}-L#{item.end_line}"
+        else
+          gh_line = "#L#{item.line}"
+        end
         source_module.github_file_prefix + relative_file_path + gh_line
       end
     end
@@ -228,6 +231,8 @@ module Jazzy
       item_render[:return] = Jazzy.markdown.render(item.return) if item.return
       item_render[:parameters] = item.parameters if item.parameters.any?
       item_render[:url] = item.url if item.children.any?
+      item_render[:start_line] = item.start_line
+      item_render[:end_line] = item.end_line
       item_render.reject { |_, v| v.nil? }
     end

data/lib/jazzy/docset_builder.rb CHANGED Viewed

@@ -58,7 +58,7 @@ module Jazzy
       end
       def copy_docs
-        files_to_copy = Pathname.glob(generated_docs_dir + '**/*') -
+        files_to_copy = Pathname.glob(generated_docs_dir + '*') -
           [docset_dir, output_dir]
         FileUtils.mkdir_p documents_dir

data/lib/jazzy/executable.rb ADDED Viewed

@@ -0,0 +1,44 @@
+module Jazzy
+  module Executable
+    class IO < Array
+      def initialize(io = nil)
+        @io = io
+      end
+      def <<(value)
+        super
+      ensure
+        @io << value.to_s if @io
+      end
+      def to_s
+        join("\n")
+      end
+    end
+    class << self
+      def execute_command(executable, args, raise_on_failure)
+        require 'shellwords'
+        bin = `which #{executable.to_s.shellescape}`.strip
+        raise "Unable to locate the executable `#{executable}`" if bin.empty?
+        require 'open4'
+        stdout, stderr = IO.new, IO.new($stderr)
+        options = { stdout: stdout, stderr: stderr, status: true }
+        status  = Open4.spawn(bin, *args, options)
+        unless status.success?
+          full_command = "#{bin.shellescape} #{args.map(&:shellescape)}"
+          output  = stdout.to_s << stderr.to_S
+          if raise_on_failure
+            raise "#{full_command}\n\n#{output}"
+          else
+            warn("[!] Failed: #{full_command}")
+          end
+        end
+        [stdout.to_s, status]
+      end
+    end
+  end
+end

data/lib/jazzy/gem_version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.1.4' unless defined? Jazzy::VERSION
+  VERSION = '0.1.5' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/jazzy_markdown.rb CHANGED Viewed

@@ -7,10 +7,6 @@ module Jazzy
     include Redcarpet::Render::SmartyPants
     include Rouge::Plugins::Redcarpet
-    def paragraph(text)
-      "<p class=\"para\">#{text}</p>"
-    end
     def header(text, header_level)
       text_slug = text.gsub(/[^a-zA-Z0-9]+/, '_')
         .downcase

data/lib/jazzy/partials/footer.mustache CHANGED Viewed

@@ -1,4 +1,4 @@
 <section id="footer">
-  <p class="copyright">&copy; {{year}} <a class="link" href="{{author_website}}" target="_blank" rel="external">{{author_name}}</a>. All rights reserved. (Last updated: {{date}})</p>
-  <p class="copyright">Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
+  <p>&copy; {{year}} <a class="link" href="{{author_website}}" target="_blank" rel="external">{{author_name}}</a>. All rights reserved. (Last updated: {{date}})</p>
+  <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
 </section>

data/lib/jazzy/partials/header.mustache ADDED Viewed

@@ -0,0 +1,11 @@
+<header>
+  <div class="content-wrapper">
+    <p><a href="{{path_to_root}}index.html">{{module_name}} Docs</a> ({{doc_coverage}}% documented)</p>
+    {{#github_url}}
+    <p class="header-right"><a href="{{github_url}}"><img src="{{path_to_root}}img/gh.png"/>View on GitHub</a></p>
+    {{/github_url}}
+    {{#dash_url}}
+    <p class="header-right"><a href="{{dash_url}}"><img src="{{path_to_root}}img/dash.png"/>Install in Dash</a></p>
+    {{/dash_url}}
+  </div>
+</header>

data/lib/jazzy/partials/nav.mustache CHANGED Viewed

@@ -1,11 +1,11 @@
-<nav class="book-parts">
-  <ul class="nav-parts">
+<nav class="sidebar">
+  <ul class="nav-groups">
     {{#structure}}
-    <li class="part-name tasks">
+    <li class="nav-group-name">
     <a href="{{path_to_root}}{{section}}.html">{{section}}</a>
-      <ul class="nav-chapters">
+      <ul class="nav-group-tasks">
         {{#children}}
-        <li class="nav-chapter">
+        <li class="nav-group-task">
           <a href="{{path_to_root}}{{url}}">{{name}}</a>
         </li>
         {{/children}}

data/lib/jazzy/partials/parameter.mustache CHANGED Viewed

@@ -1,11 +1,11 @@
 <tr>
-  <td scope="row">
+  <td>
     <code>
-    <em class="term">{{name}}</em>
+    <em>{{name}}</em>
     </code>
   </td>
   <td>
-    <div class="definition">
+    <div>
       {{{discussion}}}
     </div>
   </td>

data/lib/jazzy/partials/task.mustache CHANGED Viewed

@@ -1,41 +1,38 @@
 <div class="task-group">
-  <div class="task-name-container">
-    {{#pre_separator}}<hr/>{{/pre_separator}}
-    <a name="/{{uid}}"></a>
-    {{#name}}
-    <a name="//apple_ref/swift/Section/{{name}}" class="dashAnchor"></a>
-    <a href="#/{{uid}}">
-      <h3 class="section-name">{{name}}</h3>
-    </a>
-    {{/name}}
-    {{#post_separator}}<hr/>{{/post_separator}}
-  </div>
-  <ul class="task-group-list">
+  {{#name}}
+    <div class="task-name-container">
+      <a name="/{{uid}}"></a>
+      <a name="//apple_ref/swift/Section/{{name}}" class="dashAnchor"></a>
+      <a href="#/{{uid}}">
+        <h3 class="section-name">{{name}}</h3>
+      </a>
+    </div>
+  {{/name}}
+  <ul>
     {{#items}}
-    <li class="item symbol">
-      <div class="task-group-term">
+    <li class="item">
+      <div>
         <code>
-        <a name="/{{usr}}">
+        <a name="/{{usr}}"></a>
         <a name="//apple_ref/swift/{{dash_type}}/{{name}}" class="dashAnchor"></a>
-        <a class="x-instance-method Swift" href="#/{{usr}}">{{name}}</a>
+        <a class="token" href="#/{{usr}}">{{name}}</a>
         </code>
       </div>
       <div class="height-container">
-        <div class="pointy-thing-container"></div>
-        <section class="section instance-method">
-          <div class="pointy-thing"></div>
+        <div class="pointer-container"></div>
+        <section class="section">
+          <div class="pointer"></div>
           {{#abstract}}
           <div class="abstract">
             {{{abstract}}}
             {{#url}}
-            <a href="{{{path_to_root}}}{{{url}}}" class="see-more">See more</a>
+            <a href="{{{path_to_root}}}{{{url}}}" class="slightly-smaller">See more</a>
             {{/url}}
           </div>
           {{/abstract}}
           {{#declaration}}
           <div class="declaration">
             <h4>Declaration</h4>
             <div class="Swift">
               <p class="aside-title">Swift</p>
               {{{declaration}}}
@@ -43,9 +40,9 @@
           </div>
           {{/declaration}}
           {{#parameters.count}}
-          <div class="parameters">
+          <div>
             <h4>Parameters</h4>
-            <table class="graybox" border="0" cellspacing="0" cellpadding="5">
+            <table class="graybox">
               <tbody>
                 {{#parameters}}
                 {{> jazzy/partials/parameter}}
@@ -55,13 +52,13 @@
           </div>
           {{/parameters.count}}
           {{#return}}
-          <div class="result-description">
+          <div>
             <h4>Return Value</h4>
             {{{return}}}
           </div>
           {{/return}}
           {{#github_token_url}}
-          <div class="result-description view-on-github">
+          <div class="slightly-smaller">
             <a href="{{{github_token_url}}}">Show on GitHub</a>
           </div>
           {{/github_token_url}}

data/lib/jazzy/readme_generator.rb CHANGED Viewed

@@ -13,8 +13,7 @@ module Jazzy
         readme = generated_readme(source_module)
       end
-      rendered_readme = Jazzy.markdown.render(readme)
-      "<div class='readme'>#{rendered_readme}</div>"
+      Jazzy.markdown.render(readme)
     end
     def self.readme_path

data/lib/jazzy/source_declaration.rb CHANGED Viewed

@@ -18,6 +18,8 @@ module Jazzy
     attr_accessor :url
     attr_accessor :mark
     attr_accessor :access_control_level
+    attr_accessor :start_line
+    attr_accessor :end_line
     def overview
       "#{abstract}\n\n#{discussion}".strip

data/lib/jazzy/sourcekitten.rb CHANGED Viewed

@@ -2,10 +2,10 @@ require 'json'
 require 'pathname'
 require 'jazzy/config'
+require 'jazzy/executable'
+require 'jazzy/highlighter'
 require 'jazzy/source_declaration'
 require 'jazzy/source_mark'
-require 'jazzy/xml_helper'
-require 'jazzy/highlighter'
 module Jazzy
   # This module interacts with the sourcekitten command-line executable
@@ -56,7 +56,7 @@ module Jazzy
       expected_xcode_select_path =
         Pathname('/Applications/Xcode.app/Contents/Developer')
       return if xcode_developer_directory == expected_xcode_select_path
-      raise 'Please install Xcode 6.1 or 6.2 in ' \
+      raise 'Please install or symlink Xcode 6.1 or 6.2 in ' \
             "#{expected_xcode_select_path} and set as active developer " \
             'directory by running `sudo xcode-select -s ' \
             "#{expected_xcode_select_path}`"
@@ -64,7 +64,7 @@ module Jazzy
     def self.xcode_developer_directory
       dir = Pathname(`xcode-select -p`.chomp)
-      dir.directory? ? dir.realpath : nil
+      dir.directory? ? dir.expand_path : nil
     end
     def self.assert_swift_version
@@ -79,10 +79,8 @@ module Jazzy
     def self.run_sourcekitten(arguments)
       assert_xcode_location
       assert_swift_version
-      bin_path = Pathname(__FILE__).parent + 'sourcekitten/sourcekitten'
-      command = "#{bin_path} #{(arguments).join(' ')}"
-      output = `#{command}`
-      raise "Running `#{command}` failed: " + output unless $?.success?
+      bin_path = Pathname(__FILE__).parent + 'SourceKitten/sourcekitten'
+      output, _ = Executable.execute_command(bin_path, arguments, true)
       output
     end
@@ -97,13 +95,12 @@ module Jazzy
     def self.documented_child?(doc)
       return false unless doc['key.substructure']
-      doc['key.substructure'].each do |child|
-        return true if documented_child?(child)
-      end
-      false
+      doc['key.substructure'].any? { |child| documented_child?(child) }
     end
     def self.should_document?(doc)
+      return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
       # Always document extensions, since we can't tell what ACL they are
       return true if doc['key.kind'] == 'source.lang.swift.decl.extension'
@@ -121,41 +118,62 @@ module Jazzy
       make_default_doc_info(declaration)
     end
-    def self.parameters_from_xml(xml)
-      xml.xpath('Parameters/Parameter').map do |parameter_el|
+    def self.make_paragraphs(doc, key)
+      return nil unless doc[key]
+      doc[key].map do |p|
+        if para = p['Para']
+          Jazzy.markdown.render(para)
+        elsif verbatim = p['Verbatim']
+          Jazzy.markdown.render("```\n#{verbatim}```\n")
+        else
+          warn "Jazzy could not recognize the `#{p.keys.first}` tag. " \
+               'Please report this by filing an issue at ' \
+               'https://github.com/realm/jazzy/issues along with the comment ' \
+               'including this tag.'
+          Jazzy.markdown.render(p.values.first)
+        end
+      end.join
+    end
+    def self.parameters(doc)
+      (doc['key.doc.parameters'] || []).map do |p|
         {
-          name: XMLHelper.xpath(parameter_el, 'Name'),
-          discussion: Jazzy.markdown.render(
-              XMLHelper.xpath(parameter_el, 'Discussion') || '',
-            ),
+          name: p['name'],
+          discussion: make_paragraphs(p, 'discussion'),
         }
       end
     end
     def self.make_doc_info(doc, declaration)
-      return nil unless should_document?(doc)
-      xml_key = 'key.doc.full_as_xml'
-      return process_undocumented_token(doc, declaration) unless doc[xml_key]
+      return unless should_document?(doc)
+      unless doc['key.doc.full_as_xml']
+        return process_undocumented_token(doc, declaration)
+      end
-      xml = Nokogiri::XML(doc[xml_key]).root
-      declaration.line = XMLHelper.attribute(xml, 'line').to_i
-      declaration.column = XMLHelper.attribute(xml, 'column').to_i
+      declaration.line = doc['key.doc.line']
+      declaration.column = doc['key.doc.column']
       declaration.declaration = Highlighter.highlight(
-        doc['key.parsed_declaration'] || XMLHelper.xpath(xml, 'Declaration'),
+        doc['key.parsed_declaration'] || doc['key.doc.declaration'],
         'swift',
       )
-      declaration.abstract = XMLHelper.xpath(xml, 'Abstract')
-      declaration.discussion = XMLHelper.xpath(xml, 'Discussion')
-      declaration.return = XMLHelper.xpath(xml, 'ResultDiscussion')
+      stripped_comment = string_until_first_rest_definition(
+        doc['key.doc.comment'],
+      ) || ''
+      declaration.abstract = Jazzy.markdown.render(stripped_comment)
+      declaration.discussion = ''
+      declaration.return = make_paragraphs(doc, 'key.doc.result_discussion')
-      nodoc = ->(string) { string.to_s.include? '<dt>nodoc</dt>' }
-      return if nodoc[declaration.abstract] || nodoc[declaration.discussion]
-      declaration.parameters = parameters_from_xml(xml)
+      declaration.parameters = parameters(doc)
       @documented_count += 1
     end
+    def self.string_until_first_rest_definition(string)
+      matches = /^\s*:[^\s]+:/.match(string)
+      return string unless matches
+      string[0...matches.begin(0)]
+    end
     def self.make_substructure(doc, declaration)
       if doc['key.substructure']
         declaration.children = make_source_declarations(
@@ -197,6 +215,8 @@ module Jazzy
           doc['key.annotated_decl'],
         )
         declaration.access_control_level = acl
+        declaration.start_line = doc['key.parsed_scope.start']
+        declaration.end_line = doc['key.parsed_scope.end']
         next unless make_doc_info(doc, declaration)
         make_substructure(doc, declaration)

data/spec/integration_spec.rb CHANGED Viewed

@@ -46,7 +46,7 @@ require 'rubygems'
 require 'bundler/setup'
 require 'pretty_bacon'
 require 'colored'
-require 'clintegracon'
+require 'CLIntegracon'
 CLIntegracon.configure do |c|
   c.spec_path = ROOT + 'spec/integration_specs'
@@ -88,7 +88,7 @@ describe_cli 'jazzy' do
       behaves_like cli_spec 'document_alamofire',
                             '-m Alamofire -a Alamofire ' \
                             '-u https://nshipster.com/alamofire ' \
-                            '-x -project,Alamofire.xcodeproj ' \
+                            '-x -project,Alamofire.xcodeproj,-dry-run ' \
                             '-g https://github.com/Alamofire/Alamofire ' \
                             '--github-file-prefix https://github.com/' \
                             'Alamofire/Alamofire/blob/1.1.0 ' \
@@ -107,6 +107,7 @@ describe_cli 'jazzy' do
                             '-m MiscJazzyFeatures -a Realm ' \
                             '-u https://github.com/realm/jazzy ' \
                             '-g https://github.com/realm/jazzy ' \
+                            '-x -dry-run ' \
                             '--min-acl private'
     end
   end

data/spec/sourcekitten_spec.rb CHANGED Viewed

@@ -10,7 +10,7 @@ module Jazzy
       SourceKitten.stubs(:`)
         .returns '/Applications/Xcode-Beta.app/Contents/Developer'
       should.raise { SourceKitten.assert_xcode_location }.message.should
-        .match %r{Please install Xcode.*/Applications/Xcode.app}
+        .match %r{Please install or symlink Xcode.*/Applications/Xcode.app}
     end
     it 'validates the current xcode version' do