Jazzy docs generation workflow

[maratal]

No description provided.

[lawrence-forooghian]

I'm getting an error when I try to run Scripts/jazzy.sh locally - does it work for you?

$ ./Scripts/jazzy.sh

/Users/lawrence/code/ably/ably-cocoa/Source/include/Ably/Ably.h:1:9: fatal error: could not build module 'Foundation'
/Users/lawrence/.rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/jazzy-0.14.2/lib/jazzy/sourcekitten.rb:657:in `block in expand_extensions': undefined method `include?' for nil:NilClass (NoMethodError)
        from /Users/lawrence/.rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/jazzy-0.14.2/lib/jazzy/sourcekitten.rb:656:in `map'
        from /Users/lawrence/.rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/jazzy-0.14.2/lib/jazzy/sourcekitten.rb:656:in `expand_extensions'
        from /Users/lawrence/.rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/jazzy-0.14.2/lib/jazzy/sourcekitten.rb:1080:in `parse'
        from /Users/lawrence/.rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/jazzy-0.14.2/lib/jazzy/doc_builder.rb:155:in `build_docs_for_sourcekitten_output'
        from /Users/lawrence/.rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/jazzy-0.14.2/lib/jazzy/doc_builder.rb:86:in `build'
        from /Users/lawrence/.rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/jazzy-0.14.2/bin/jazzy:16:in `<top (required)>'
        from /Users/lawrence/.rbenv/versions/3.0.0/bin/jazzy:23:in `load'
        from /Users/lawrence/.rbenv/versions/3.0.0/bin/jazzy:23:in `<main>'

[maratal]

/Users/runner/work/ably-cocoa/ably-cocoa/Source/include/Ably/ARTDeltaCodec.h:2:9: fatal error: 'AblyDeltaCodec/AblyDeltaCodec.h' file not found error was due to absence of dependencies. I've added this step here 94bfab9

Also there were multiple warnings like warning: no 'assign', 'retain', or 'copy' attribute is specified - 'assign' is assumed [-Wobjc-property-no-attribute]. I've created a separate issue for that: #1433

Regarding local jazzy command. Strangely enough I began experiencing the same error /Users/lawrence/code/ably/ably-cocoa/Source/include/Ably/Ably.h:1:9: fatal error: could not build module 'Foundation', but only after I've installed sourcekitten and used it directly like that:

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

jazzy command works without issues. I still have Big Sur and ruby 2.6.3 though, will update to Monterey and check it again. But CI build is now clean. @lawrence-forooghian

[lawrence-forooghian]

@maratal great news about the CI build, thanks!

As for my local issues, I just tried with Ruby 2.6.3, didn't make a difference, still get the error. As for the rest of my environment, I'm on macOS 12.4, Xcode 13.4.1.

[maratal]

@maratal great news about the CI build, thanks!

As for my local issues, I just tried with Ruby 2.6.3, didn't make a difference, still get the error. As for the rest of my environment, I'm on macOS 12.4, Xcode 13.4.1.

Yes, after fresh install of macOS 12.4 and Xcode 13.4.1. it's now reproducible. @lawrence-forooghian

[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 realm/jazzy#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 "):

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).

[lawrence-forooghian]

Hey @maratal - I haven't read your above comment in detail, but unfortunately on commit 3f7a94d I'm still getting the exact same error as before on my machine.