[SR-15634] Remove need to pass --fallback-... CLI arguments in most cases
#194
Comments
|
@swift-ci create |
|
To implement what's described in the Description there are few different places to look at: The display name and identifier decoded in 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 When there's no DocC catalog the bundle is created in
|
|
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! 🙂 |
|
That's great to hear. Feel free to reach out if you have any questions. |
|
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) |
|
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 |
Would you mind pointing out which branch you were working? If I guess correctly, should it be |
Maybe you can start to create a draft PR. So that we can comment on it and give you some feedback |
|
Thanks for the advice! I just opened a draft PR #391, I look forward to your feedback! |
Additional Detail from JIRA
md5: 675dc1ff1939386d0c186c42c940543c
Issue Description:
Swift-DocC requires some minimal information about the documentation that it's building to name and identify the documentation. This information can be specified in a couple of different ways:
If the documentation has a DocC catalog (a folder with a .docc extension) with an Info.plist file in it, then the documentation's name and identifier can be read from the content of that identifier.
If the documentation doesn't have a DocC catalog, or the catalog doesn't have an Info.plist file, then the documentation's name and identifier can be provided as two command line arguments (
----``fallback-display-nameand--``fallback-bundle-identifier). These arguments are prefixed with "fallback" because they are only used when a value can't be retrieved from the DocC catalog's Info.plist file (for example if that file doesn't exist).The documentation's identifier doesn't need to follow a specific format. That said, the identifier needs to be unique to the current documentation build. In almost all cases documentation is built separately for each "bundle", so uniqueness isn't an issue. Further, even when multiple "bundles" are built together their display name are most often unique enough.
Because of this, a suitable documentation identifier can almost always be derived from the documentation's display name. When that derived identifier isn't unique, this can be identified and diagnosed and that issue can be resolved by providing a unique identifier either as an Info.plist value or as a custom
--``fallback-bundle-identifierargument.Further, a suitable documentation display name can almost always be derived from other information in the documentation "bundle". A documentation bundle consist of either a DocC catalog or a collection of symbol graph files, or both.
Most documentation is about a single module. In this case, when all the bundle's symbol graph files are about the same module, then that module name is a good display name in almost all cases. When it's not, a custom name can be provided as a
--fallback-display-nameargument.If the bundle contains symbol graph files about more than one module or if the bundle doesn't contain any symbol graph files, then it's less clear what a good display name would be. However, since the developer need to provide a custom display name if none is derived but only needs to provide a custom display name if the derived one is incorrect, I feel that deriving a display name that's good enough in many cases still provide value here. In this situation, I feel that deriving the documentation from the DocC catalogs filename (without the file extension) is likely to be a good enough value in many cases.
Since the documentation's version information is already optional, making the above changes to derive the documentation's identifier and display name would remove most of the cases when developer's need to pass
--fallback...CLI arguments.Summary
If a documentation bundle has no specified identifier, derive the identifier from the bundle's display name.
If a documentation bundle has no specified display name:
and it has symbol graph files about a single module, derive the display name from the module's name
and it has a DocC catalog, derive the display name from the catalog's filename (without the file extension)
otherwise (if the bundle has no DocC catalog and symbol graphs about multiple modules, raise the same error as today that a display is missing name and needs to be provided.
The text was updated successfully, but these errors were encountered: