add way to generate docs for an SPM module

[jpsim]

This adds a way to easily document SPM packages. However, there's a stack overflow issue in the yaml parser library I'm using to parse the Swift Package Manager's build info (behrang/YamlSwift#26), which means that packages that generate a yaml file over ~350 lines has a decent chance of crashing.

$ git clone https://github.com/qutheory/vapor.git
$ cd vapor
$ swift build
$ echo "$(head -n 384 .build/debug.yaml)" > .build/debug.yaml # workaround for https://github.com/behrang/YamlSwift/issues/26
$ export TOOLCHAIN_DIR=/Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-2016-05-03-a.xctoolchain
$ sourcekitten doc --spm-module Vapor > vapor.json

You can then run jazzy on the output:

$ jazzy \
  --clean \
  --sourcekitten-sourcefile vapor.json \
  --author Qutheory \
  --author_url http://qutheory.io \
  --github_url https://github.com/qutheory/vapor \
  --github-file-prefix https://github.com/qutheory/vapor/tree/0.8.2 \
  --module-version 0.8.2 \
  --module Vapor \
  --root-url https://static.realm.io/jazzy_demo/Vapor

Which generates this: https://static.realm.io/jazzy_demo/Vapor

[orta]

Dreamy, I was researching some of this last night 👍

[norio-nomura]

make package fails by this PR.

mkdir -p "/tmp/SourceKitten.dst/usr/local/Frameworks" "/tmp/SourceKitten.dst/usr/local/bin"
mv -f "/tmp/SourceKitten.dst/Applications/sourcekitten.app/Contents/Frameworks/SourceKittenFramework.framework" "/tmp/SourceKitten.dst/usr/local/Frameworks/SourceKittenFramework.framework"
mv -f "/tmp/SourceKitten.dst/Applications/sourcekitten.app/Contents/MacOS/sourcekitten" "/tmp/SourceKitten.dst/usr/local/bin/sourcekitten"
rm -rf "/tmp/SourceKitten.dst/Applications/sourcekitten.app"
pkgbuild \
        --component-plist "Source/sourcekitten/Components.plist" \
        --identifier "com.sourcekitten.SourceKitten" \
        --install-location "/" \
        --root "/tmp/SourceKitten.dst" \
        --version "0.12.2" \
        "SourceKitten.pkg"
pkgbuild: Reading components from Source/sourcekitten/Components.plist
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/YamlSwift.framework
pkgbuild: error: Component path "/tmp/SourceKitten.dst/usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/YamlSwift.framework" does not exist.
make: *** [package] Error 1

[norio-nomura]

Patch for fixing above error:

diff --git a/Source/sourcekitten/Components.plist b/Source/sourcekitten/Components.plist
index 90b2284..0679bf7 100644
--- a/Source/sourcekitten/Components.plist
+++ b/Source/sourcekitten/Components.plist
@@ -19,7 +19,7 @@
                <key>BundleOverwriteAction</key>
                <string></string>
                <key>RootRelativeBundlePath</key>
-               <string>/usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/YamlSwift.framework</string>
+               <string>/usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yaml.framework</string>
            </dict>
            <dict>
                <key>BundleOverwriteAction</key>

After fixed above error, pkgbuild fails as following:

mkdir -p "/tmp/SourceKitten.dst/usr/local/Frameworks" "/tmp/SourceKitten.dst/usr/local/bin"
mv -f "/tmp/SourceKitten.dst/Applications/sourcekitten.app/Contents/Frameworks/SourceKittenFramework.framework" "/tmp/SourceKitten.dst/usr/local/Frameworks/SourceKittenFramework.framework"
mv -f "/tmp/SourceKitten.dst/Applications/sourcekitten.app/Contents/MacOS/sourcekitten" "/tmp/SourceKitten.dst/usr/local/bin/sourcekitten"
rm -rf "/tmp/SourceKitten.dst/Applications/sourcekitten.app"
pkgbuild \
        --component-plist "Source/sourcekitten/Components.plist" \
        --identifier "com.sourcekitten.SourceKitten" \
        --install-location "/" \
        --root "/tmp/SourceKitten.dst" \
        --version "0.12.2" \
        "SourceKitten.pkg"
pkgbuild: Reading components from Source/sourcekitten/Components.plist
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yaml.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework
pkgbuild: Adding component at usr/local/Frameworks/SourceKittenFramework.framework
pkgbuild: error: Path "/tmp/SourceKitten.dst/usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yaml.framework" is not a valid bundle component (using destination path "/tmp/SourceKitten.dst")
make: *** [package] Error 1

And I filed behrang/YamlSwift#27 for fixing the pkgbuild error.

[norio-nomura]

YamlSwift's build configuration has been updated behrang/YamlSwift#27 (comment).
Updating YamlSwift to latest fixes the pkgbuild error.

[jpsim]

Wow, thanks for identifying and fixing all these issues @norio-nomura! You're amazing!

I also haven't been unable to reproduce behrang/YamlSwift#26 with Release builds, so I can live with this limitation for now.