jazzy 0.0.4 → 0.0.6

data/lib/jazzy/partials/tasks.mustache

@@ -0,0 +1,7 @@
+{{#tasks.count}}
+<section class="section task-group-section">
+  {{#tasks}}
+  {{> jazzy/partials/task}}
+  {{/tasks}}
+</section>
+{{/tasks.count}}

data/lib/jazzy/source_declaration.rb

@@ -0,0 +1,19 @@
+module Jazzy
+  class SourceDeclaration
+    attr_accessor :kindNamePlural
+    attr_accessor :kind
+    attr_accessor :kindName
+    attr_accessor :file
+    attr_accessor :line
+    attr_accessor :column
+    attr_accessor :usr
+    attr_accessor :name
+    attr_accessor :declaration
+    attr_accessor :abstract
+    attr_accessor :discussion
+    attr_accessor :return
+    attr_accessor :children
+    attr_accessor :parameters
+    attr_accessor :url
+  end
+end

data/lib/jazzy/sourcekitten.rb

@@ -0,0 +1,146 @@
+require 'active_support/inflector'
+require 'json'
+require 'open3'
+
+require 'jazzy/config'
+require 'jazzy/source_declaration'
+require 'jazzy/xml_helper'
+
+module Jazzy
+  # This module interacts with the sourcekitten command-line executable
+  module SourceKitten
+    # SourceKit-provided token kinds along with their human-readable descriptions
+    # @todo Make sure this list is exhaustive for source.lang.swift.decl.*
+    def self.kinds
+      {
+        'source.lang.swift.decl.function.method.class' => 'Class Method',
+        'source.lang.swift.decl.var.class' => 'Class Variable',
+        'source.lang.swift.decl.class' => 'Class',
+        'source.lang.swift.decl.function.constructor' => 'Constructor',
+        'source.lang.swift.decl.function.destructor' => 'Destructor',
+        'source.lang.swift.decl.var.global' => 'Global Variable',
+        'source.lang.swift.decl.enumelement' => 'Enum Element',
+        'source.lang.swift.decl.enum' => 'Enum',
+        'source.lang.swift.decl.extension' => 'Extension',
+        'source.lang.swift.decl.function.free' => 'Function',
+        'source.lang.swift.decl.function.method.instance' => 'Instance Method',
+        'source.lang.swift.decl.var.instance' => 'Instance Variable',
+        'source.lang.swift.decl.var.local' => 'Local Variable',
+        'source.lang.swift.decl.var.parameter' => 'Parameter',
+        'source.lang.swift.decl.protocol' => 'Protocol',
+        'source.lang.swift.decl.function.method.static' => 'Static Method',
+        'source.lang.swift.decl.var.static' => 'Static Variable',
+        'source.lang.swift.decl.struct' => 'Struct',
+        'source.lang.swift.decl.function.subscript' => 'Subscript',
+        'source.lang.swift.decl.typealias' => 'Typealias',
+      }
+    end
+
+    # Group root-level docs by kind and add as children to a group doc element
+    def self.group_docs(docs, kind)
+      kind_name_plural = kinds[kind].pluralize
+      group, docs = docs.partition { |doc| doc.kind == kind }
+      docs << SourceDeclaration.new.tap do |sd|
+        sd.name = kind_name_plural
+        sd.kind = 'Overview'
+        sd.abstract = "The following #{kind_name_plural.downcase} are available " \
+          'globally.'
+        sd.children = group
+      end if group.count > 0
+      docs
+    end
+
+    # Generate doc URL by prepending its parents URLs
+    # @return [Hash] input docs with URLs
+    def self.make_doc_urls(docs, parents)
+      docs.each do |doc|
+        if doc.children.count > 0
+          # Create HTML page for this doc if it has children
+          parents_slash = parents.count > 0 ? '/' : ''
+          doc.url = parents.join('/') + parents_slash + doc.name + '.html'
+          doc.children = make_doc_urls(doc.children, parents + [doc.name])
+        else
+          # Don't create HTML page for this doc if it doesn't have children
+          # Instead, make its link a hash-link on its parent's page
+          doc.url = parents.join('/') + '.html#/' + doc.usr
+        end
+      end
+      docs
+    end
+
+    # Run sourcekitten with given arguments and return
+    # STDOUT, STDERR and exit status
+    def self.run_sourcekitten(arguments)
+      bin_path = File.expand_path(File.join(File.dirname(__FILE__), '../../bin'))
+      Open3.capture3("#{bin_path}/sourcekitten #{(arguments).join(' ')}")
+    end
+
+    def self.make_source_declarations(docs)
+      declarations = []
+      docs.each do |doc|
+        if doc.key?('key.diagnostic_stage')
+          return make_source_declarations(doc['key.substructure'])
+        end
+        declaration = SourceDeclaration.new
+        declaration.kind = doc['key.kind']
+        next unless declaration.kind =~ /^source\.lang\.swift\.decl\..*/
+        next if declaration.kind == 'source.lang.swift.decl.var.parameter'
+
+        declaration.kindName = kinds[declaration.kind]
+
+        raise 'Please file an issue on https://github.com/realm/jazzy/issues ' \
+          "about adding support for `#{declaration.kind}`" unless declaration.kindName
+
+        declaration.kindNamePlural = declaration.kindName.pluralize
+        declaration.file = doc['key.filepath']
+        declaration.usr = doc['key.usr']
+        declaration.name = doc['key.name']
+
+        if doc['key.doc.full_as_xml']
+          xml = Nokogiri::XML(doc['key.doc.full_as_xml']).root
+          declaration.line = XMLHelper.attribute(xml, 'line').to_i
+          declaration.column = XMLHelper.attribute(xml, 'column').to_i
+          declaration.declaration = XMLHelper.xpath(xml, 'Declaration')
+          declaration.abstract = XMLHelper.xpath(xml, 'Abstract')
+          declaration.discussion = XMLHelper.xpath(xml, 'Discussion')
+          declaration.return = XMLHelper.xpath(xml, 'ResultDiscussion')
+
+          parameters = []
+          xml.xpath('Parameters/Parameter').each do |parameter_el|
+            parameters << {
+              name: XMLHelper.xpath(parameter_el, 'Name'),
+              discussion: Jazzy.markdown.render(
+                  XMLHelper.xpath(parameter_el, 'Discussion'),
+                ),
+            }
+          end
+          declaration.parameters = parameters
+        else
+          # TODO: Fix these
+          declaration.line = 0
+          declaration.column = 0
+          declaration.abstract = 'Undocumented'
+          declaration.parameters = []
+        end
+
+        if doc['key.substructure']
+          declaration.children = make_source_declarations(doc['key.substructure'])
+        else
+          declaration.children = []
+        end
+        declarations << declaration
+      end
+      declarations
+    end
+
+    # Parse sourcekitten STDOUT+STDERR output as JSON
+    # @return [Hash] structured docs
+    def self.parse(sourcekitten_output)
+      docs = make_source_declarations(JSON.parse(sourcekitten_output))
+      kinds.keys.each do |kind|
+        docs = group_docs(docs, kind)
+      end
+      make_doc_urls(docs, [])
+    end
+  end
+end

data/lib/jazzy/xml_helper.rb

@@ -0,0 +1,15 @@
+require 'nokogiri'
+
+module Jazzy
+  module XMLHelper
+    # Gets value of XML attribute or nil (i.e. file in <Class file="Musician.swift"></Class>)
+    def self.attribute(node, name)
+      node.attributes[name].value if node.attributes[name]
+    end
+
+    # Gets text in XML node or nil (i.e. s:cMyUSR <USR>s:cMyUSR</USR>)
+    def self.xpath(node, xpath)
+      node.xpath(xpath).text if node.xpath(xpath).text.length > 0
+    end
+  end
+end

data/spec/integration_spec.rb

@@ -0,0 +1,89 @@
+
+# ------------------------------------ #
+#  Jazzy Integration tests             #
+# ------------------------------------ #
+
+#-----------------------------------------------------------------------------#
+
+# The following integrations tests are based on file comparison.
+#
+# 1.  For each test there is a folder with a `before` and `after` subfolders.
+# 2.  The contents of the before folder are copied to the `TMP_DIR` folder and
+#     then the given arguments are passed to the `JAZZY_BINARY`.
+# 3.  After the jazzy command completes the execution the each file in the
+#     `after` subfolder is compared to the contents of the temporary
+#     directory.  If the contents of the file do not match an error is
+#     registered.
+#
+# Notes:
+#
+# - The output of the jazzy command is saved in the `execution_output.txt` file
+#   which should be added to the `after` folder to test the Jazzy UI.
+# - To create a new test, just create a before folder with the environment to
+#   test, copy it to the after folder and run the tested pod command inside.
+#   Then just add the tests below this files with the name of the folder and
+#   the arguments.
+#
+# Rationale:
+#
+# - Have a way to track precisely the evolution of the artifacts (and of the
+#   UI) produced by jazzy (git diff of the after folders).
+# - Allow uses to submit pull requests with the environment necessary to
+#   reproduce an issue.
+# - Have robust tests which don't depend on the programmatic interface of
+#   Jazzy. These tests depend only the binary and its arguments an thus are
+#   suitable for testing Jazzy regardless of the implementation (they could even
+#   work for a Swift one)
+
+#-----------------------------------------------------------------------------#
+
+# @return [Pathname] The root of the repo.
+#
+ROOT = Pathname.new(File.expand_path('../../', __FILE__)) unless defined? ROOT
+$:.unshift((ROOT + 'spec').to_s)
+
+require 'rubygems'
+require 'bundler/setup'
+require 'pretty_bacon'
+require 'colored'
+require 'clintegracon'
+
+CLIntegracon.configure do |c|
+  c.spec_path = ROOT + 'spec/integration_specs'
+  c.temp_path = ROOT + 'tmp'
+
+  # Ignore certain OSX files
+  c.ignores '.DS_Store'
+  c.ignores '.git'
+  c.ignores /^(?!(docs\/|execution_output.txt))/
+
+  c.hook_into :bacon
+end
+
+describe_cli 'jazzy' do
+
+  subject do |s|
+    s.executable = "ruby #{ROOT + 'bin/jazzy'}"
+    s.environment_vars = { 'JAZZY_FAKE_DATE' => '2014-01-01' }
+    s.default_args = []
+    s.replace_path ROOT.to_s, 'ROOT'
+  end
+
+  describe 'jazzy' do
+    describe 'Creates docs with a module name, author name, project URL, ' \
+      'xcodebuild options, and github info' do
+      behaves_like cli_spec 'document_alamofire',
+                            '-m Alamofire -a Alamofire ' \
+                            '-u https://nshipster.com/alamofire ' \
+                            '-x -project,Alamofire.xcodeproj ' \
+                            '-g https://github.com/Alamofire/Alamofire ' \
+                            '--github-file-prefix https://github.com/Alamofire/Alamofire/blob/1.1.0'
+    end
+    describe 'Creates docs for Swift project with a variety of contents' do
+      behaves_like cli_spec 'misc_jazzy_features',
+                            '-m MiscJazzyFeatures -a Realm ' \
+                            '-u https://github.com/realm/jazzy ' \
+                            '-g https://github.com/realm/jazzy '
+    end
+  end
+end

data/spec/integration_specs/document_alamofire/after/docs/Classes.html

@@ -0,0 +1,266 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Classes  Reference</title>
+    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
+    <meta charset='utf-8'>
+    <script src="js/jquery.min.js" defer></script>
+    <script src="js/jazzy.js" defer></script>
+  </head>
+  <body id="reference" class="Swift">
+    <a title="Classes  Reference"></a>
+    <header>
+      <div class="content-wrapper">
+        <p class="header-text"><a href="#">Alamofire Docs</a></p>
+        <p id="header-links"><a href="https://github.com/Alamofire/Alamofire"><img id="header-icon" src="img/gh.png" height="16px" width="16px" />View on GitHub</a></p>
+        <p id="header-links"><a href=""><img id="header-icon" src="img/dash.png" height="16px" width="16px" />Install in Dash</a></p>
+      </div>
+    </header>
+    <section id="valence">
+      <div class="content-wrapper">
+        <p id="hierarchial_navigation">
+        <a href="#" id="design_resources_link">Alamofire Reference</a>
+        <img id="carat" src="img/carat.png" height="10px" width="6px" />
+        Classes  Reference
+        </p>
+      </div>
+    </section>
+    <div class="content-wrapper">
+      <nav class="book-parts">
+        <ul class="nav-parts">
+          <li class="part-name tasks">
+          <a href="Classes.html">Classes</a>
+            <ul class="nav-chapters">
+              <li class="nav-chapter">
+                <a href="Classes/Manager.html">Manager</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Classes/Request.html">Request</a>
+              </li>
+            </ul>
+          </li>
+          <li class="part-name tasks">
+          <a href="Global Variables.html">Global Variables</a>
+            <ul class="nav-chapters">
+              <li class="nav-chapter">
+                <a href="Global Variables.html#/s:v9Alamofire20AlamofireErrorDomainSS">AlamofireErrorDomain</a>
+              </li>
+            </ul>
+          </li>
+          <li class="part-name tasks">
+          <a href="Enums.html">Enums</a>
+            <ul class="nav-chapters">
+              <li class="nav-chapter">
+                <a href="Enums.html#/s:O9Alamofire6Method">Method</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Enums/ParameterEncoding.html">ParameterEncoding</a>
+              </li>
+            </ul>
+          </li>
+          <li class="part-name tasks">
+          <a href="Extensions.html">Extensions</a>
+            <ul class="nav-chapters">
+              <li class="nav-chapter">
+                <a href="Extensions/String.html">String</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/NSURL.html">NSURL</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/NSURLComponents.html">NSURLComponents</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/NSURLRequest.html">NSURLRequest</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/NSURLRequest.html">NSURLRequest</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Manager.html">Manager</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Manager.html">Manager</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Extensions/Request.html">Request</a>
+              </li>
+            </ul>
+          </li>
+          <li class="part-name tasks">
+          <a href="Functions.html">Functions</a>
+            <ul class="nav-chapters">
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9AlamofireP33_A313450CFC1FC3D0CBEF4411412DB9E810URLRequestFTOS_6MethodPS_20URLStringConvertible__CSo12NSURLRequest">URLRequest(_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire7requestFTOS_6MethodPS_20URLStringConvertible_10parametersGSqGVSs10DictionarySSPSs9AnyObject___8encodingOS_17ParameterEncoding_CS_7Request">request(_:_:parameters:encoding:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire7requestFPS_21URLRequestConvertible_CS_7Request">request(_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire6uploadFTOS_6MethodPS_20URLStringConvertible_CSo5NSURL_CS_7Request">upload(_:_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire6uploadFTPS_21URLRequestConvertible_CSo5NSURL_CS_7Request">upload(_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire6uploadFTOS_6MethodPS_20URLStringConvertible_CSo6NSData_CS_7Request">upload(_:_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire6uploadFTPS_21URLRequestConvertible_CSo6NSData_CS_7Request">upload(_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire6uploadFTOS_6MethodPS_20URLStringConvertible_CSo13NSInputStream_CS_7Request">upload(_:_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire6uploadFTPS_21URLRequestConvertible_CSo13NSInputStream_CS_7Request">upload(_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire8downloadFTOS_6MethodPS_20URLStringConvertible_FTCSo5NSURLCSo17NSHTTPURLResponse_S2__CS_7Request">download(_:_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire8downloadFTPS_21URLRequestConvertible_FTCSo5NSURLCSo17NSHTTPURLResponse_S1__CS_7Request">download(_:_:)</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Functions.html#/s:F9Alamofire8downloadFT10resumeDataCSo6NSDataFTCSo5NSURLCSo17NSHTTPURLResponse_S1__CS_7Request">download(resumeData:_:)</a>
+              </li>
+            </ul>
+          </li>
+          <li class="part-name tasks">
+          <a href="Protocols.html">Protocols</a>
+            <ul class="nav-chapters">
+              <li class="nav-chapter">
+                <a href="Protocols/URLStringConvertible.html">URLStringConvertible</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Protocols/URLRequestConvertible.html">URLRequestConvertible</a>
+              </li>
+            </ul>
+          </li>
+          <li class="part-name tasks">
+          <a href="Typealiases.html">Typealiases</a>
+            <ul class="nav-chapters">
+              <li class="nav-chapter">
+                <a href="Typealiases.html#/s:C9Alamofire7Request10Validation">Validation</a>
+              </li>
+              <li class="nav-chapter">
+                <a href="Typealiases.html#/s:C9Alamofire7Request23DownloadFileDestination">DownloadFileDestination</a>
+              </li>
+            </ul>
+          </li>
+        </ul>
+      </nav>
+      <div class="pixel-line"></div>
+      <div class="rubber-band-gap"></div>
+      <article class="chapter">
+      <a name="/"></a>
+        <h1 class="chapter-name">Classes</h1>
+        <section>
+          <section class="section">
+            <p class="para">The following classes are available globally.</p>
+          </section>
+          <section class="section task-group-section">
+            <div class="task-group">
+              <div class="task-name-container">
+                <a name="/Children"></a>
+                <a href="#/Children">
+                  <h3 class="section-name"></h3>
+                </a>
+              </div>
+              <ul class="task-group-list">
+                <li class="item symbol">
+                  <div class="task-group-term">
+                    <code>
+                    <a name="/s:C9Alamofire7Manager">
+                    <a class="x-instance-method Swift" href="#/s:C9Alamofire7Manager">Manager</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="abstract">
+                        <p class="para">Responsible for creating and managing <code>Request</code> objects, as well as their underlying <code>NSURLSession</code>.</p>
+                      </div>
+                      <div class="declaration">
+                        <h4>Declaration</h4>
+            
+                        <div class="Swift">
+                          <p class="aside-title">Swift</p>
+                          <p class="para">
+                          <code>public class Manager</code>
+                          </p>
+                        </div>
+                      </div>
+                      <div class="result-description view-on-github">
+                        <a href="https://github.com/Alamofire/Alamofire/blob/1.1.0/Source/Alamofire.swift#L215">Show on GitHub</a>
+                      </div>
+                    </section>
+                  </div>
+                </li>
+                <li class="item symbol">
+                  <div class="task-group-term">
+                    <code>
+                    <a name="/s:C9Alamofire7Request">
+                    <a class="x-instance-method Swift" href="#/s:C9Alamofire7Request">Request</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="abstract">
+                        <p class="para">Responsible for sending a request and receiving the response and associated data from the server, as well as managing its underlying <code>NSURLSessionTask</code>.</p>
+                      </div>
+                      <div class="declaration">
+                        <h4>Declaration</h4>
+            
+                        <div class="Swift">
+                          <p class="aside-title">Swift</p>
+                          <p class="para">
+                          <code>public class Request</code>
+                          </p>
+                        </div>
+                      </div>
+                      <div class="result-description view-on-github">
+                        <a href="https://github.com/Alamofire/Alamofire/blob/1.1.0/Source/Alamofire.swift#L522">Show on GitHub</a>
+                      </div>
+                    </section>
+                  </div>
+                </li>
+              </ul>
+            </div>
+          </section>
+        </section>
+        <section id="footer">
+          <p class="copyright">&copy; 2014 <a class="link" href="https://nshipster.com/alamofire" target="_blank" rel="external">Alamofire</a>. All rights reserved. (Last updated: 2014-01-01)</p>
+          <p class="copyright">Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.0.5</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
+        </section>
+      </article>
+    </div>
+  </body>
+</div>
+</html>