Adopt jazzy.sh to execute locally without errors

[maratal]

Jazzy stopped crashing after I've replaced --framework-root . with --framework-root Source. But it still struggled with error 'AblyDeltaCodec/AblyDeltaCodec.h' file not found. Then there were some manipulations with the make command (make update_carthage_dependencies_<platform>). After that it never appeared again no matter what to cleanup and what --framework-root value was. So I can't say for sure what "fixed" this crash.

But like on previous macOS installation, when I installed sourcekitten separately, it was there again:

sourcekitten doc --objc $(pwd)/Source/Ably.h
  -- -x objective-c
  -isysroot $(xcrun --show-sdk-path --sdk iphoneos)
  -I $(pwd) -fmodules > objcDoc.json

/Users/admin/Work/ably-cocoa/Source/Ably.h:1:9: fatal error: could not build module 'Foundation'

After iphoneos was replaced to iphonesimulator (as suggested in this thread https://github.com/realm/jazzy/issues/840):

sourcekitten doc --objc $(pwd)/Source/Ably.h
  -- -x objective-c
  -isysroot $(xcrun --show-sdk-path --sdk iphonesimulator)
  -I $(pwd) -fmodules > objcDoc.json

/Users/admin/Work/ably-cocoa/Source/Ably.h:9:9: fatal error: 'Ably/ARTLog.h' file not found

And after adding symlink to Source directory with the module name (as suggested in this article https://nicedoc.io/realm/jazzy/ObjectiveC.md):

/Users/admin/Work/ably-cocoa/Ably/ARTDeltaCodec.h:2:9: fatal error: 'AblyDeltaCodec/AblyDeltaCodec.h' file not found.

But proper objcDoc.json file was generated regardless this error.

Also, as that article suggests, playing with clang command might be helpful, as jazzy relies on that, but the thing is that it doesn't work even in our main branch:

clang -c -x objective-c -isysroot $(xcrun --show-sdk-path) -I $(pwd) Source/Ably.h -fmodules

In file included from Source/Ably.h:60:
/Users/admin/Work/ably-cocoa/Ably/ARTDeltaCodec.h:2:9: fatal error: 'AblyDeltaCodec/AblyDeltaCodec.h' file not found
#import <AblyDeltaCodec/AblyDeltaCodec.h>
        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 error generated.

Adding -F to pass Carthage frameworks doesn't help (from that article: "If you are happy to build the framework project before generating docs and all the problematic paths have the form ModuleName/PublicHeader.h then have clang resolve those includes to the built framework by passing -F <path of directory containing ModuleName.framework>"):

clang -c -x objective-c -isysroot $(xcrun --show-sdk-path) \
  -I $(pwd) Source/Ably.h \
  -F Carthage/Build \
  -fmodules

So, at this point I kinda ran out of ideas. Let me know if the last version of jazzy.sh works for you @lawrence-forooghian (it works for me locally and on CI without errors).

Originally posted by maratal in https://github.com/ably/ably-cocoa/issues/1428#issuecomment-1158892249

┆Issue is synchronized with this Jira Task by Unito