jazzy cannot run on mac_ios_engine Mac arm bot

[jmagman]

I tried to swap mac_ios_engine orchestrator to arm64 Macs to leverage that bot capacity in flutter/engine#41185. However it failed on the obj-c-doc step with "Could not find 'sqlite3'"

 /Volumes/Work/s/w/ir/cache/ruby/.cipd/pkgs/0/7BJOF4R2SzfKZnk0BZpiDRQmb_RD79GlZrPpOydeydIC/lib/ruby/3.1.0/rubygems/specification.rb:1453:in `rescue in block in activate_dependencies': Could not find 'sqlite3' (~> 1.3) among 131 total gem(s) (Gem::MissingSpecError)
 Checked in 'GEM_PATH=/Users/chrome-bot/.local/share/gem/ruby/3.1.0:/Volumes/Work/s/w/ir/cache/ruby/.cipd/pkgs/0/7BJOF4R2SzfKZnk0BZpiDRQmb_RD79GlZrPpOydeydIC/lib/ruby/gems/3.1.0:/Volumes/Work/s/w/ir/cache/gems/ruby/3.1.0' at: /Volumes/Work/s/w/ir/cache/gems/ruby/3.1.0/specifications/jazzy-0.14.3.gemspec, execute `gem env` for more information

https://ci.chromium.org/p/flutter/builders/try/Mac%20mac_ios_engine/8101

flutter/ruby/mac-arm64 and flutter/jazzy/mac-arm64 cipd packages are being installed. See also #118464

cc @godofredoc

[chinmaygarde]

Instead of Jazzy, could we just use something like Doxygen for Obj-C doc generation? I feel like this has been a constant source of issues on CI.

[godofredoc]

Instead of Jazzy, could we just use something like Doxygen for Obj-C doc generation? I feel like this has been a constant source of issues on CI.

+1 on removing the jazzy dependency if possible. Last time I spent 2 weeks on getting it working properly.

@zanderso, @dnfield do you remember what was the outcome of the conversation about replacing jazzy with something else from a few months ago?

[dnfield]

I have no objections to using doxygen instead of jazzy. I have a vague memory of looking into doing it a few years ago, and at the time it seemed as complicated or more than just using jazzy. That may have changed or I may be remembering wrong.

[flutter-triage-bot]

Issue is assigned to multiple teams (infra, engine). Please ensure the issue has only one team-* label at a time. Use fyi-* labels to have another team look at the issue without reassigning it.
The triaged-engine label is irrelevant if there is no team-engine label or fyi-engine label.

[gspencergoog]

It seems that Doxygen is already configured for the Engine repo (there's a Doxyfile at least that seems to build real docs), but it seems to only be used for making sure that there aren't any undocumented APIs on iOS.

Is there any problem with publishing that instead of using the Jazzy results?

(cc @gaaclarke, who added the Doxyfile)

[dnfield]

IMHO we should prioritize what will work better on CI for this rather than worrying about if it looks the same as what Jazzy was producing.

[gspencergoog]

Works for me. Doxygen seems like it's fine just cramming APIs from multiple platforms into one page, though, so I'm trying to figure out how to separate it into different runs that make sense. For example, it took code from the two different files called FlutterEngine.mm in both iOS and macOS, and crammed them all into one FlutterEngine page when I tried to run it on the entire tree. I'm running it multiple times on subsets of the tree now, and that seems to work better.

[gspencergoog]

For iOS, what should the migration be for the existing docs? For instance, they are currently hosted under https://api.flutter.dev/objcdoc/, built by jazzy. I'd like to change the name to something like https://api.flutter.dev/ios_embedder_docs/ and build them with Doxygen.

I don't see how we can keep legacy links valid and redirect them without just building the jazzy docs and continuing to serve them.

Should we just build and serve both, but only link the doxygen docs in the API docs, and then stop building the old ones once the next stable comes out with the updated links? (or a year after they come out?)

[zanderso]

@gspencergoog Can we start removing stuff like this:

https://github.com/flutter/engine/blob/main/.ci.yaml#L438

and

https://flutter.googlesource.com/recipes/+/refs/heads/main/recipe_modules/flutter_deps/api.py#668

cc @godofredoc

[gspencergoog]

Not yet. I haven't yet landed the Framework side changes that include links to the new documentation generated by doxygen, so we should continue to produce the Jazzy docs until I can replace them with the doxygen ones.

Draft PR is here: #131356

[gspencergoog]

Also, how concerned are we that the old URLs to the Jazzy docs won't match the URLs for the new docs? I don't want to invalidate people's links, but we also can't keep generating the Jazzy docs.

[zanderso]

Can you add some more detail about what links will be changing?

[gspencergoog]

If you have a link to the current set of Jazzy-produced docs, you have something like:
https://master-api.flutter.dev/objcdoc/Classes/FlutterEngine.html

Once I make the change to the doxygen generated docs, it will be something like this:
https://master-api.flutter.dev/ios-embedder/interface_flutter_engine.html

[gspencergoog]

I would suggest some kind of redirect scheme, but that's likely to a) be super complex and b) not necessarily map 1:1 (some things in Jazzy docs might only have one URL, where in doxygen they might be several URLs, or vice versa).

I thought about keeping around the most recently generated Jazzy docs, but those would just quickly get out of date.

We could perhaps redirect all of the docs under "objcdoc/*" to the main index file for the doxygen docs. At least then they could search for what they were looking for, and wouldn't get a 404.

[yusuf-goog]

@gspencergoog is there something infra needs to do for this issue?

[gspencergoog]

There are some spurious files/directories in the CIPD packages that have to do with doxygen, and those can be permanently removed. since those executables were never in use. This directory can be removed: https://chrome-infra-packages.appspot.com/p/flutter/doxygen

We'll have to keep the jazzy CIPD package around to be able to build historical builds.

Right now, Jazzy is still being run, but I'll make a PR to stop doing that now that we have doxygen links in the API docs.

[gspencergoog]

Okay, Jazzy is no longer being used, and we've switched to Doxygen.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.