Converter: allow converting a directory w/o .docc extension
#585
Conversation
|
@swift-ci test |
|
I think this change in behavior could be considered "breaking" for integrations with build workflows when the project doesn't have a documentation catalog. Before these changes, when the build workflow would call Footnotes
|
|
Since we just want the support here – could we start be adding an additional flag that allows for this and suppresses the diagnostic? Something like In general we don't expect people to use unidentified DocC catalogs because it breaks existing integration points with SwiftPM and Xcode. So removing the diagnostic by default seems like a worse UX for the average user in order to enable this completely reasonable, but more power-user feature. |
|
@swift-ci test |
|
@swift-ci test |
| @@ -18,6 +18,8 @@ public protocol DocumentationWorkspaceDataProvider { | |||
| /// use `UUID().uuidString` for the provider's identifier. | |||
| var identifier: String { get } | |||
|
|
|||
| var allowArbitraryCatalogDirectories: Bool { get } | |||
There was a problem hiding this comment.
AFAICT this property is specific to LocalFileSystemDataProvider. I think it'd make be better to move it there or to a new protocol that it can conform to.
| @@ -174,6 +174,9 @@ extension Docc { | |||
| @available(*, deprecated, message: "Doxygen support is now enabled by default.") | |||
| public var experimentalParseDoxygenCommands = false | |||
|
|
|||
| @Flag(help: "Allow catalog directories without the `.docc` extension.") | |||
| var allowArbitraryCatalogDirectories = false | |||
There was a problem hiding this comment.
I think that we'd want to label this "experimental" until it's been discussed in the forums.
There was a problem hiding this comment.
To clarify; I don't it needs to be discussed very formally but it would be good to at least have some post that pitches adding this flag since we don't expect developers to monitor PRs
|
@swift-ci test |
|
@swift-ci test |
Summary
When converting a directory that only has Markdown files in it, it feels redundant to rename the directory to have a
.doccextension just for the sake of rendering those files. It would be great if DocC supported converting any directory regardless of its extension out of the box.This new behavior is conditional on the newly introduced
--allow-arbitrary-catalog-directoriesflag.Dependencies
N/A
Testing
You can test this with the Swift compiler documentation at https://github.com/apple/swift/tree/main/docs, which has no
.doccextension and is just a collection of Markdown files.Steps:
git clone https://github.com/apple/swiftswift run docc convert --allow-arbitrary-catalog-directories --transform-for-static-hosting --output-path output swift/docsChecklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded