Initial work for mixed Swift and ObjC Sourcekitten input

[joesus]

Initial attempt at mixing Swift and ObjectiveC.

Todo:

• Unit tests
• A process / instructions for providing input
• Figuring out how to get language stub to appear in the template (following the same pattern as language did not seem to work, probably missed a step)

[joesus]

@johnfairh, this clearly needs quite a bit of work still but wanted to get some eyes on it early. Thank you for the help in getting this far!

[johnfairh]

Added some minor comments.

language_stub is used at a few levels of the mustache templates so will need providing in more than just render_item. I think the doc.mustache usage matches the structure built in document() and document_markdown(), and the top usage in task.mustache matches make_task().

It's a bit challenging to know what to set this to for the higher-level places: they're both collections of things that could be a mix of ObjC and Swift. I suppose the backwards-compatible safe thing is to use the --objc flag to decide as today.

[johnfairh]

Added a commit to sort out the highlighting problems that were breaking CI -- feel free to throw it away + refactor as you prefer. One breakage was the case where the stuff being hilighted is from markdown (eg. readme) so neither swift nor objc. Not sure why it was sometimes getting the language backwards.

[joesus]

Thanks for fixing the highlighting code! What's the next steps for this? CLI flag to pass in Jazzy input to combine? Or maybe just documenting on the sourcekitten command that it will take a file that has mixed jazzy input? What do you think would be least impact? (Assuming least impact is the goal for this change)

[johnfairh]

As discussed I pushed a commit to allow --sourcekitten-sourcefile to take multiple json files and do the merge internally. Seems to work for me - see what you think.

Stuff left to do then that I can think of:

• Test and fix any breakage of --hide-declarations
• Add a Swift file to misc_jazzy_objc_features and update spec recipe to include mixed project in CI
• Decide what to do about language_stub & do it
• Check what Dash does with a mixed docset
• Add usage instructions to readme

Other stuff we talked about that might not be needed for a first release:

• Swift extensions of ObjC types and vice versa: merge them.
• Multi-language declaration at the top of pages.

[joesus]

@johnfairh I'll try and take this piece by piece:

1. Test and fix any breakage of --hide-declarations
   Fixed

2. Add a Swift file to misc_jazzy_objc_features and update spec recipe to include mixed project in CI
   Need to do still.

3. Decide what to do about language_stub & do it
   Need to do still.

4. Check what Dash does with a mixed docset
   Need to do still.

5. Add usage instructions to readme
   Added

Hopefully will have some time tomorrow to tackle item 2.
Thanks!

[johnfairh]

Nice, makes the inherently messy hide-declarations a bit cleaner.

[joesus]

@johnfairh, update:

Check what Dash does with a mixed docset

Seems to work the same as the website. Notably it does generate the docset as a hidden file due to lack of a module name but it seems this is a known issue (#921).

This is what the mixed docs looks like in Dash. (changed the docset name so that it could be imported)

[johnfairh]

Ignore the cocoapods CI failure for now - CI issue to do with cocoapods setup, I think fixed on master.

[joesus]

This is coming together nicely! I'll take a crack at updating the specs but might not get to it until this weekend. Any tips or pitfalls to watch out for? Thanks!

[johnfairh]

Roughly: rebase this branch to master, fork and branch realm/jazzy-integration-specs and change the spec/integration_specs submodule to point there. Update misc_jazzy_objc_features, then the driver code to invoke jazzy is in spec/integration_spec.rb. bundle exec rake rebuild_integration_fixtures to generate new stuff to check in - shouldn't change any other projects.

[johnfairh]

Updated the MiscJazzyObjCFeatures project to include a Swift file and some cross-language extensions to show how they (aren't) handled.

[johnfairh]

I think this is ready to be merged now.

Swift extensions are displayed separately rather than merged into their ObjC types (see sample project). We should fix this soon to make the docs easier to read.

Users have to run sourcekitten separately. We could fix this one day by teaching jazzy how to run multiple build commands -- useful for many situations including App Extensions and the #ifdef problem.

The outstanding issue from comments above was language_stub -- this turned out to be about generating Dash tables-of-contents which appear to work fine with the changes.

[joesus]

This is great! I’ll start on the follow-up this weekend. :)

[jpsim]

Nice. This feature has been years in the making, thanks for pushing it through @joesus & @johnfairh 🎉

[bamx23]

When these changes are expected to be in release(0.11.3 or 0.12.0)?

[johnfairh]

There's a bug we need to fix to do with contents pages being overwritten. I should have some time next week if @joesus doesn't beat me to it.