Add support for Jazzy for code where a Xcode project doesn't exist

[loretoparisi]

I have a Swift project that is not a Xcode project, it is a RemObjects Fire project - https://github.com/loretoparisi/swift-promise-example.
If I try to run jazzy from the sources folder src/ (that is here: https://github.com/loretoparisi/swift-promise-example/tree/master/StaticLibrary/SharedProject/src ) I get an error that I suppose is due to the fact that this is not a Xcode project:

Running xcodebuild

Could not parse compiler arguments from `xcodebuild` output.

Please confirm that `xcodebuild` is building a Swift module.

Saved `xcodebuild` log file: /var/folders/mm/qbx_84b57sgf_f9j0cxmj__r0000gn/T/xcodebuild-FAD08B0F-059E-415B-968E-D4074BD7D21D.log

Failed to generate documentation
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/sourcekitten.rb:140:in `run_sourcekitten'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:57:in `block in build'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:55:in `chdir'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:55:in `build'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/bin/jazzy:15:in `<top (required)>'
    from /usr/bin/jazzy:23:in `load'
    from /usr/bin/jazzy:23:in `<main>

So is it possibile to run jazzy for non Xcode projects?

[orta]

You could create a podspec for it, but all that would do is automate the creation of a xcodeproject for you.

[jpsim]

Yeah, jazzy basically requires an Xcode project to detect what the entirety of the swiftc and clang arguments are. This is because the inception of jazzy predates other Swift compilers which became popular after Apple open sourced Swift, like using swiftc directly and using the Swift Package Manager.

There are definitely ways to avoid the Xcode dependency, but they're certainly not documented and would require some minor modifications to jpsim/SourceKitten, but you'd still need deep knowledge of how that works to do those small changes. So I'm afraid you're on your own here (unless you follow @orta's advice) until jazzy adds support for something like the Swift Package Manager.

[kylebrowning]

This would be a great feature as I have a framework with no Xcode project.

[pigeondotdev]

Converting this issue from a question to a feature request since I agree with @kylebrowning. That would be a cool feature, especially with SPM and non-Xcode proj Swift code.

[dimpiax]

@istx25 any progress?

[pigeondotdev]

We have not actively started working on this feature, afaik. Feel free to take on the feature if you'd like to though.

[dimpiax]

On which technology this feature can be written?

[pigeondotdev]

SourceKitten is written in Swift and Jazzy is written in Ruby. I'm not exactly sure where these changes need to be made but definitely feel free to look into that or @jpsim could probably put you in the right direction.

[dimpiax]

Who knows, maybe I will find some time for implementing this useful feature.
@jpsim could you provide me some details about?

[SDGGiesbrecht]

I’m not familiar with RemObjects Fire, but I use jazzy with the Swift Package Manager.

swift package generate-xcodeproj
jazzy

Making a different type of project look enough like a package to let the Swift Package Manager generate the Xcode project may be relatively simple. Try something like this as a bare‐bones starting point:

cd ../Somewhere/Outside/The/Project
mkdir TemporaryPackage
cd TemporaryPackage
swift package init
cp -r /Path/Of/Actual/Project/Root Sources/TemporaryPackage
rm Sources/TemporaryPackage.swift
swift package generate-xcodeproj
jazzy
cp -r docs /Path/Of/Documentation/Output
cd ..
rm -rf TemporaryPackage

With real paths, the above script is already sufficient to run jazzy, provided the project contains only .swift files . You may need to tailor the script for details like the module name or to remove any filetypes the Swift Package Manager does not understand.

I wrote it in shell so it is fast to try, but the script can also be re‐writen in whatever language you like (Jazzy is in Ruby). Once you get it working for your project, if you decide to modify it to be widely‐applicable and no longer hard coded for your particular project, you can submit a pull request.

I suspect the simplest way to integrate this into Jazzy itself would be a Jazzy configuration option (something like not_an_xcode_project) that causes the before and after sections of the above script (converted to Ruby) to run near the beginning and end of Jazzy’s execution.

Note: All this still assumes Xcode itself is present on the system. Making Jazzy work without it would be tantamount to starting Jazzy over from scratch. Ergo, Jazzy will never run on Linux.

[jpsim]

If your project supports the Swift Package Manager, you don't need an Xcode project to generate docs for it. For example:

$ brew install sourcekitten
$ git clone https://github.com/qutheory/vapor.git
$ cd vapor
$ git checkout 1.3.8
$ swift build
$ sourcekitten doc --spm-module Vapor > vapor.json
$ 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/1.3.8 \
  --module-version 1.3.8 \
  --module Vapor \
  --root-url https://static.realm.io/jazzy_demo/Vapor

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

At some point, I'll build a more direct way to do this with a single command using jazzy.

But right now, it's not too complicated, just three commands: swift build, sourcekitten doc, jazzy.

[kylebrowning]

@jpsim Link is 404

[jpsim]

it's still uploading. Shouldn't take more than another 60 seconds.

[kylebrowning]

This doesnt work with iOS, tvOS, or watchOS executables because swift build only builds executables for the host system.

[jpsim]

@kylebrowning my comment above explicitly stated that this is an option of your project supports the Swift Package Manager...

[SDGGiesbrecht]

Edit: This comment is obsolete. See the next comment instead.

---

This doesnt work with iOS, tvOS, or watchOS executables because swift build only builds executables for the host system.

@kylebrowning, the package just has to build on the host system; it need not actually run.

For some iOS (et al.) frameworks, the Swift Package Manager may still be a reasonable hack until something better comes along. The amount of work it involves depends on the particular project and how many iOS‐only symbols it deals with.

Function implementations the host system cannot build can be surrounded with:

/// Documention that should generate.
public func doSomething() -> String {
    #if os(macOS)
    return String()
    #else
    // Actual implementation here.
    #endif
}

That way, on iOS, nothing has changed, but macOS can now build the API.

The same can be done to import lines to erase the need to build any dependencies the host cannot handle.

Problematic parameter types and return values can be solved by defining empty versions of those types for macOS:

#if os(macOS)
/// :nodoc:
public struct UIView {}
#endif

[SDGGiesbrecht]

This doesnt work with iOS, tvOS, or watchOS executables because swift build only builds executables for the host system.

I didn’t let that stop me. Workspace can now stitch the Swift Package Manager, iOS, and Jazzy together.

To see a demonstration, paste the following script into Terminal, and voilà—instant documentation. (Assuming Xcode 8.2.1 and Jazzy 0.7.4 are on the local device.)

# Create an empty package
mkdir MyLibrary
cd MyLibrary
swift package init
git init
cd ..

# Delete the template code:
rm -rf MyLibrary/Sources/MyLibrary.swift
rm -rf MyLibrary/Tests

# Add OS‐specific code:
echo $'#if os(macOS)\n    /// Does macOS stuff.\n    public func doMacOSStuff() {}\n#elseif os(iOS)\n    /// Does iOS stuff.\n    public func doIOSStuff() {}\n#elseif os(watchOS)\n    /// Does watchOS stuff.\n    public func doWatchOSStuff() {}\n#elseif os(tvOS)\n    /// Does tvOS stuff.\n    public func doTVOSStuff() {}\n#endif' > MyLibrary/Sources/MyLibrary.swift

# Display source
open MyLibrary/Sources/MyLibrary.swift

# Make sure Workspace is installed
# More Information: https://github.com/SDGGiesbrecht/Workspace#workspace
git clone https://github.com/SDGGiesbrecht/Workspace
Workspace/Refresh\ Workspace\ \(macOS\).command
rm -rf Workspace

# Apply Workspace to the project
# More Information: https://github.com/SDGGiesbrecht/Workspace#setup
cd MyLibrary
~/.Workspace/Workspace/.build/release/workspace refresh
cd ..

# Configure Workspace
# More Information: https://github.com/SDGGiesbrecht/Workspace/blob/master/Documentation/Configuring Workspace.md#configuring-workspace
echo $'Manage Xcode: True\nGenerate Documentation: True\nAutomatically Take On New Responsibilities: False\nSkip Simulator: True' > "MyLibrary/.Workspace Configuration.txt"

# Run Workspace (which includes Jazzy)
# More Information: https://github.com/SDGGiesbrecht/Workspace/blob/master/Documentation/Documentation Generation.md#documentation-generation
cd MyLibrary
~/.Workspace/Workspace/.build/release/workspace validate
cd ..

# Display result
open MyLibrary/docs/macOS/index.html
open MyLibrary/docs/iOS/index.html
open MyLibrary/docs/watchOS/index.html
open MyLibrary/docs/tvOS/index.html

@kylebrowning, let me know if there are additional project‐specific hurdles still in the way.

[cianiandreadev]

Any news here? I would like to run Jazzy as step in my CI on a Linux system. Any hope to support this one day?

[SDGGiesbrecht]

@cianiandreadev, there is still no progress towards Linux support within the Jazzy project itself—Jazzy is built on top of Xcode.

---

However, if...

• your project has a repository on GitHub
• your project can be built with the Swift Package Manager

...then Workspace can be easily set up with Travis CI to run Jazzy remotely and push the documentation to a gh‐pages branch. (You can pull that branch to copy the documentation elsewhere too.) Here is an example of a project that does it this way.

In this manner Jazzy can be used even if all you have locally are Linux machines.

[johnfairh]

Well, sourcekitten runs on Linux and supports SPM directly, so the technique in #487 (comment) should work -- no Xcode dependencies I can see?

[SDGGiesbrecht]

Well, sourcekitten runs on Linux and supports SPM directly

...sort of. It takes extra work and know‐how to set up and even then is somewhat unreliable. Two significant complications are the out‐of‐package dependency on SourceKit and the fact that Foundation is not integral to the operating system. Anyone considering this route may find it useful to read these related issues in the repositories for SourceKitten and SwiftLint (another SourceKitten client): realm/SwiftLint#732, jpsim/SourceKitten#433, realm/SwiftLint#2026.

I have tried three separate times over the last year to write a script that could reliably shim SourceKitten and smooth over the complications, but I have been forced to give up each time. (If someone else succeeds, I will happily be the first to start using it.)

But yes, if you can get SourceKitten working, then the technique farther up is viable on Linux.

Note that the technique is very straightforward on macOS.

[SDGGiesbrecht]

SourceKitten is much easier to use from Linux now. The notes in the last few comments are out of date.

[johnfairh]

Calling this addressed by #1089 adding direct SwiftPM support.

Retain #495 for direct non-Darwin support.