-
Notifications
You must be signed in to change notification settings - Fork 151
Add support for custom scripts #1056
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Lucca-mito
wants to merge
1
commit into
swiftlang:main
Choose a base branch
from
Lucca-mito:main
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
98 changes: 98 additions & 0 deletions
98
Sources/SwiftDocC/SwiftDocC.docc/Resources/CustomScripts.spec.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| { | ||
| "openapi": "3.0.0", | ||
| "info": { | ||
| "title": "Custom Scripts", | ||
| "description": "This spec describes the permissible contents of a custom-scripts.json file in a documentation catalog, which is used to add custom scripts to a DocC-generated website.", | ||
| "version": "0.0.1" | ||
| }, | ||
| "paths": {}, | ||
| "components": { | ||
| "schemas": { | ||
| "Scripts": { | ||
| "type": "array", | ||
| "description": "An array of custom scripts, which is the top-level container in a custom-scripts.json file.", | ||
| "items": { | ||
| "oneOf": [ | ||
| { "$ref": "#/components/schemas/ExternalScript" }, | ||
| { "$ref": "#/components/schemas/LocalScript" }, | ||
| { "$ref": "#/components/schemas/InlineScript" } | ||
| ] | ||
| } | ||
| }, | ||
| "Script": { | ||
| "type": "object", | ||
| "description": "An abstract schema representing any script, from which all three script types inherit.", | ||
| "properties": { | ||
| "type": { | ||
| "type": "string", | ||
| "description": "The `type` attribute of the HTML script element." | ||
| }, | ||
| "run": { | ||
| "type": "string", | ||
| "enum": ["on-load", "on-navigate", "on-load-and-navigate"], | ||
| "description": "Whether the custom script should be run only on the initial page load, each time the reader navigates after the initial page load, or both." | ||
| } | ||
| } | ||
| }, | ||
| "ScriptFromFile": { | ||
| "description": "An abstract schema representing a script from an external or local file; that is, not an inline script.", | ||
| "allOf": [ | ||
| { "$ref": "#/components/schemas/Script" }, | ||
| { | ||
| "properties": { | ||
| "async": { "type": "boolean" }, | ||
| "defer": { "type": "boolean" } | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| "ExternalScript": { | ||
| "description": "A script at an external URL.", | ||
| "allOf": [ | ||
| { "$ref": "#/components/schemas/ScriptFromFile" }, | ||
| { | ||
| "required": ["url"], | ||
| "properties": { | ||
| "url": { "type": "string" }, | ||
| "integrity": { "type": "string" } | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| "LocalScript": { | ||
| "description": "A script from a local file.", | ||
| "allOf": [ | ||
| { "$ref": "#/components/schemas/ScriptFromFile" }, | ||
| { | ||
| "required": ["name"], | ||
| "properties": { | ||
| "name": { | ||
| "type": "string", | ||
| "description": "The name of the local script file, optionally including the '.js' extension." | ||
| }, | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| "InlineScript": { | ||
| "description": "A script whose source code is in the custom-scripts.json file itself.", | ||
| "allOf": [ | ||
| { "$ref": "#/components/schemas/Script" }, | ||
| { | ||
| "required": ["code"], | ||
| "properties": { | ||
| "code": { | ||
| "type": "string", | ||
| "description": "The source code of the inline script." | ||
| } | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| "requestBodies": {}, | ||
| "securitySchemes": {}, | ||
| "links": {}, | ||
| "callbacks": {} | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why not append the bundle ID here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(Also, if the relative path to the
custom-scriptsfolder is always"/custom-scripts"then it’s easier to find it in the renderer code.)There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see. That's not how combined documentation works (which is already available as an experimental feature). Non-content files aren't automatically included in the combined archive. If this was treated as an asset, a collision between archives would be treated as an error. If this file is intended to be copied over into the combined archive, it should have an archive-unique prefix and this PR should update the merge command to copy over the expected files.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey David,
Sorry for the confusion; I hadn’t read your combined-documentation proposals yet and was operating under some admittedly hasty guesswork. Having read them now — the second, lower-level pitch in particular — I wasn't able to find more information on how combined documentation handles assets.
So I looked through the
swift-docccode. But I haven't yet been able to find code for merging documentation archives, or for handling assets during that merge (the closest I could find was this, which seems related to merging assets of documentation archives given the phrasing here), or for including additional "non-symbol content for the landing page of the combined documentation" (a feature ofdocc mergeyou described in the technical pitch that could be relevant here). I'm definitely missing something obvious so apologies for the question, but where in theswift-docccodebase does documentation-archive merging happen? Essentially, I'm trying to figure out:theme-settings.jsonfiles of the archives being combined, so I can do the same tocustom-scripts.json.custom-scriptsdirectory. (Assuming that doing so wouldn't break custom scripts, which I'll also look into.)Thanks!!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The combined archive is assumed to want a consistent visual appearance across all its modules. Therefore it doesn't matter which theme-settings.json file it uses (but it only uses one of them).
In a regular archive, images are already located in a subdirectory named after the documentation's identifier. This makes merging images trivial because each subdirectory can simply be copied into the combined archives "images" directory.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Got it, thanks!
I think it makes sense to only include one of the
custom-scripts.jsonin the combined archive:theme-settings.jsonworks.custom-scripts.jsonbehaving differently would be confusing.custom-scripts.jsonthat it wants to use custom script S in its documentation website, then that by no means suggests that the developers of module A want to use S in a combined documentation website. If the developers of module A wish to use S, they can include it themselves.And if we're only including one archive's
custom-scripts.jsonin combined documentation, then we should similarly only include that archive'scustom-scripts(the archive subdirectory containing the actual scripts). After all, to continue the example in point 2 above, it would make no sense to include the scripts from B since:custom-scripts.jsonrequiring those scripts (and specifying how they should be run) would be absent.So we should only include the
custom-scripts.jsonand thecustom-scriptsof one archive, meaning that there is no need to namespace either of them with a bundle ID.Do you agree? If so, the next and last question is: where in the
swift-docccodebase is the code for the "merge" action (so I can implement the copying ofcustom-scripts.jsonandcustom-scriptsto the combined archive in the same way astheme-settings.jsonis currently handled)?Thanks again as always!