Add support for custom scripts #1056
Conversation
| @available(*, deprecated, renamed: "init(info:baseURL:symbolGraphURLs:markupURLs:miscResourceURLs:customHeader:customFooter:themeSettings:)", message: "Use 'init(info:baseURL:symbolGraphURLs:markupURLs:miscResourceURLs:customHeader:customFooter:themeSettings:)' instead. This deprecated API will be removed after 6.1 is released") | ||
| public init( | ||
| info: Info, | ||
| baseURL: URL = URL(string: "/")!, | ||
| attributedCodeListings: [String: AttributedCodeListing] = [:], | ||
| symbolGraphURLs: [URL], | ||
| markupURLs: [URL], | ||
| miscResourceURLs: [URL], | ||
| customHeader: URL? = nil, | ||
| customFooter: URL? = nil, | ||
| themeSettings: URL? = nil | ||
| ) { | ||
| self.init(info: info, baseURL: baseURL, symbolGraphURLs: symbolGraphURLs, markupURLs: markupURLs, miscResourceURLs: miscResourceURLs, customHeader: customHeader, customFooter: customFooter, themeSettings: themeSettings) | ||
| self.attributedCodeListings = attributedCodeListings | ||
| } | ||
|
|
There was a problem hiding this comment.
This is a source breaking change. Like the deprecation message says; we can't remove this until after 6.1 is released. See the "Introducing source breaking changes" section of the contributions guidelines
There was a problem hiding this comment.
This is making an unintentional source breaking change that should be undone.
Additionally, we're in the process of migrating away from LocalFileSystemDataProvider so the new code to find the custom-scripts.json file also need to be added to DocumentationContext.InputProvider. There's already a test that verifies that both implementation discover the same files which would also be good to update so that it verifies the behavior for this new type of file.
| /// | ||
| /// - Parameter bundleIdentifier: The identifier of the bundle to return download assets for. | ||
| /// - Returns: A list of all the custom scripts for the given bundle. | ||
| public func registeredCustomScripts(forBundleID bundleIdentifier: BundleIdentifier) -> [DataAsset] { |
There was a problem hiding this comment.
I would prefer if this was package level access for now so that we don't have to make more source breaking changes to change it to not have a bundle ID parameter when #1059 lands.
| @@ -3251,6 +3251,7 @@ class ConvertActionTests: XCTestCase { | |||
|
|
|||
| XCTAssertEqual(fileSystem.dump(subHierarchyFrom: targetURL.path), """ | |||
| Output.doccarchive/ | |||
| ├─ custom-scripts/ | |||
There was a problem hiding this comment.
Question: is it expected that we create this folder even if the user didn't pass any custom scripts?
There was a problem hiding this comment.
FYI, the method of input discovery in this file is about to be deprecated in #1059 and won't be used by DocC anymore.
These same changes need to be implemented in DocumentationContext.InputProvider which is what DocC will use to discover its inputs after #1057 lands.
It would also be good to update DocumentationInputsProviderTests.testDiscoversSameFilesAsPreviousImplementation() to verify that both implementations discover the custom scripts file the same. (This can happen before either of those PRs are merged)
| self.rootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: "/", sourceLanguage: .swift) | ||
| self.documentationRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.documentationFolder, sourceLanguage: .swift) | ||
| self.tutorialsRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift) | ||
| self.technologyTutorialsRootReference = tutorialsRootReference.appendingPath(urlReadablePath(info.displayName)) | ||
| self.articlesDocumentationRootReference = documentationRootReference.appendingPath(urlReadablePath(info.displayName)) | ||
| } | ||
|
|
||
| @available(*, deprecated, renamed: "init(info:baseURL:symbolGraphURLs:markupURLs:miscResourceURLs:customHeader:customFooter:themeSettings:)", message: "Use 'init(info:baseURL:symbolGraphURLs:markupURLs:miscResourceURLs:customHeader:customFooter:themeSettings:)' instead. This deprecated API will be removed after 6.1 is released") |
There was a problem hiding this comment.
FIY: Since the name of the replacement changed with the new parameter you may need to update the renamed portion of this deprecation annotation. Even if it's not needed, it's nice to do it since it enables the fixit for any code that still uses the deprecated API.
d-ronnqvist
added
the
source breaking
Summary
First-class support for adding custom scripts to a DocC-generated website. These may be local scripts, in which case the website will continue to work offline, or they may be external scripts at a user-specified URL. This support is in the form of a custom-scripts.json file, the scripting analog of theme-settings.json.
Full pitch: https://forums.swift.org/t/pitch-support-for-custom-scripts-in-docc/75357.
Dependencies
Corresponding change in swift-docc-render.
Testing
custom-scripts.jsonand the custommathjax-config.jsscript (shown in the pitch) to your documentation catalog.docc convertthe documentation catalog with your custom scripts. Observe that the modified swift-docc copiedcustom-scripts.jsonand the custom scripts into the documentation archive.Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded