Hi all!
I’d like to pitch a small change to Swift-DocC that will allow for better presentation of non-framework documentation.
This work would resolve [SR-15434] [Swift-DocC] Support custom documentation module kinds · Issue #207 · apple/swift-docc · GitHub.
The proposed implementation is available here: [SR-15434] Add support for custom (non-framework) module kinds by ethan-kusters · Pull Request #33 · apple/swift-docc · GitHub.
Not all documentation built by Swift-DocC is for frameworks. Today, Swift-DocC will build documentation for any symbol graph input it is provided, which is what allows for custom workflows like Swift-DocC’s user documentation on Swift.org. However, Swift-DocC always describes this documentation as a “Framework” on the top-level page, regardless of the contents of that symbol graph.
For example, Swift-DocC’s user documentation on Swift.org is currently described as a “Framework” on the top-level page when the documentation on that page is about using DocC as a “Tool”, not as a “Framework”.
In order to allow for a future in which Swift-DocC supports generating documentation for all sorts of non-framework targets, we should make this “Framework” text customizable.
Proposed Solution
Add support for a new key in the Info.plist
file that Swift-DocC looks for in the root of every documentation catalog. This key would allow a documentation author to specify the kind of documentation module being built. This in turn will allow Swift-DocC to accurately render non-framework documentation kinds.
In order to integrate with other tools that may not want to interact with the documentation catalog’s Info.plist
, we will also add a new command-line option to provide this information.
Today, Swift-DocC supports the following Info.plist keys:
Info.plist Key | Description |
---|---|
CFBundleDisplayName |
The display name of the bundle. |
CFBundleIdentifier |
The unique identifier of the bundle. |
CFBundleVersion |
The version of the bundle. |
CDDefaultCodeListingLanguage |
The default language identifier for code listings in the bundle. |
CDAppleDefaultAvailability |
The default availability for the various modules in the bundle. |
I propose we add a new CDDefaultModuleKind
key that would allow authors to specify the default kind that should be used for the various documentation modules in their bundle.
Several of these keys also allow for a fallback version of their value to be passed on the command-line. This allows for integration with external tools that may want to provide this information directly to docc
.
Today, Swift-DocC supports the following fallback arguments:
Command-line Argument | Corresponding Info.plist Key |
---|---|
--fallback-display-name |
CFBundleDisplayName |
--fallback-bundle-identifier |
CFBundleIdentifier |
--fallback-bundle-version |
CFBundleVersion |
--default-code-listing-language |
CDDefaultCodeListingLanguage |
I propose we also add a new command-line argument, --fallback-default-module-kind
that allows for a default module kind to be provided via the command-line in the case where one is not provided in the DocC catalog’s Info.plist. This will allow external tools that integrate with Swift-DocC to inform the documentation compiler of the kind of documentation module being built.
In the case where a default module kind is not provided via the Info.plist or the command-line, we should keep the existing behavior and describe the documentation module as a “Framework”. This will avoid regressing documentation builds for existing projects.
Alternatives Considered
Instead of providing this information via the Info.plist or the command-line, we could instead augment the symbol graph spec to allow for this information to be provided there.
There are a number of benefits to this approach. However, I see benefits in allowing this value to be provided in the documentation catalog even in a world where it can be provided in the symbol graph. There are custom use cases of Swift-DocC where whatever tool producing the symbol graph may not be able to accurately describe the module in a way the documentation author likes. In this scenario, having support for a custom kind provided in the Documentation Catalog will still be useful.
Given this, it makes sense to surface this functionality in Swift-DocC first, and continue to explore how we could also allow for the information to be provided in a symbol graph in the future.