[SR-15634] Remove need to pass `--fallback-...` CLI arguments in most cases

[apple]

[SR-15634] Remove need to pass `--fallback-...` CLI arguments in most cases

[arthurcro]

Hey! 👋 As part of the Swift Mentorship Program and with the help of my mentor, I'm hoping to make my first contribution to an open-source project. I would love to give this issue a try! 🙂

[d-ronnqvist]

That's great to hear. Feel free to reach out if you have any questions.

[arthurcro]

Thanks for the advice! I just opened a draft PR #391, I look forward to your feedback!

[d-ronnqvist]

@swift-ci create

[d-ronnqvist]

To implement what's described in the Description there are few different places to look at:

The display name and identifier decoded in init(with:bundleDiscoveryOptions: in DocumentationBundle+Info.swift
That's a good place to default to the display name when the identifier is missing. Depending on this the decoding is done, requiredKeys may also need to change.

That code doesn't know what the DocC catalog is named or what the modules are named—they know the symbols graph URLs but would need to read and decode the files to find the module name—so the last resort derived display name would need to be passed there or otherwise be made accessible somehow.

There are different code paths for creating documentation "bundles" when there's a DocC catalog and when there isn't.

When there's a DocC catalog the code path that creates the bundle is in createBundle(::options🙂 in DataProviderBundleDiscovery.swift

When there's no DocC catalog the bundle is created in GeneratedDataProvider. It also has some code to read the module names out of the symbol graph files.

DocumentationBundleInfoTests tests the existing decoding (which would be updated to cover the logic for deriving values) but it could also be good to test the full flow in ConvertActionTests by passing a few different variations of bundle discovery options both with and without a DocC catalog (the documentationBundleURL: argument to ConvertAction

[Kyle-Ye]

Hi @arthurcro, are you still working on this? Let us know we can help!

(This is indeed a annoying issue for the user site, and hope we can solve it ASAP)

[arthurcro]

Hey @Kyle-Ye! My apologies for the delay in closing this issue. I actually have something working on a fork but I got stuck adding a test covering the full flow in ConvertActionTests and I haven't had the opportunity to pick it up again. I'm not quite sure how to get started adding a test there. I'd love some help with this if you have time! 🙂

[Kyle-Ye]

Hey @Kyle-Ye! My apologies for the delay in closing this issue. I actually have something working on a fork but I got stuck adding a test covering the full flow in ConvertActionTests and I haven't had the opportunity to pick it up again. I'm not quite sure how to get started adding a test there. I'd love some help with this if you have time! 🙂

Would you mind pointing out which branch you were working? If I guess correctly, should it be https://github.com/arthurcro/swift-docc/tree/arthurcro/improve-deriving-cli-arguments

[Kyle-Ye]

I'd love some help with this if you have time!

Maybe you can start to create a draft PR. So that we can comment on it and give you some feedback