Add support for custom scripts

[Lucca-mito]

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

• Unit tests added.
• To test the feature end-to-end, you'll need to use the version of swift-docc-render with the corresponding changes. Follow the steps in the pitch for adding any custom scripts you want to your documentation website (your own scripts, or a library such as MathJax or D2). If you want a specific example to test the implementation:
  • Copy the custom-scripts.json and the custom mathjax-config.js script (shown in the pitch) to your documentation catalog.
  • Add LaTeX expressions to your in-source documentation.
  • docc convert the documentation catalog with your custom scripts. Observe that the modified swift-docc copied custom-scripts.json and the custom scripts into the documentation archive.
  • Preview the documentation archive. Observe that the LaTeX expressions are rendered on the page.
• Live demo: see here and here. The LaTeX expressions in the documentation text are dynamically rendered into equations via custom scripts.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary
  • Existing documentation does not need to change. New documentation for this feature will be added after the design and implementation are finalized.

[d-ronnqvist]

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.

[d-ronnqvist]

Why not append the bundle ID here?

[Lucca-mito]

• So that projects with combined documentation of multiple targets (when that lands) can share scripts between the documentation bundles of each target. I suspect that authors of packages with multiple targets will want scripts to be shared: nobody wants to set up their MathJax scripts once per target.
• In practice, even in documentation webpages for multiple targets, custom scripts loaded into the browser are global. For example, scripts that define the same global function can conflict with each other irrespective of the bundle they were loaded from. So namespacing the script files by bundle ID is moot.

(Also, if the relative path to the custom-scripts folder is always "/custom-scripts" then it’s easier to find it in the renderer code.)

[d-ronnqvist]

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.

[d-ronnqvist]

minor: A test helper like this which doesn't forward the callers line and file information would attribute a test failure to the wrong line. This is fixed by both:

• adding arguments that default to #filePath and #line
• explicitly passing those values to each test assertion in this helper.

Also, the "test" prefix is typically used for tests themselves, not test helpers.

Suggested change

	private func test(
	whether predicate: (URL) -> Bool,
	matchesFilesNamed fileName: String,
	withExtension extension: String
	) {
	private func assertThat(
	_ predicate: (URL) -> Bool,
	matchesFilesNamed fileName: String,
	withExtension extension: String,
	file: StaticString = #filePath,
	line: UInt = #line
	) {

[d-ronnqvist]

This added file is never verified anywhere. Other similar files are verified here.