Improved theme settings support

[mportiz08]

Bug/issue #, if applicable: 97040358

Summary

This PR updates the existing support for the theme-settings.json file to be more fully featured and capable. This is the Swift-DocC-Render implementation support for my recent forum proposal titled
Customizing the look and feel of Swift-DocC-Render.

Major Changes:

• removed default theme-settings.json file since it only existed for pseudo documentation purposes (full OpenAPI spec will be created for Swift-DocC as well as conceptual docs)
• fixed bugs with overwritten colors not working right when switching between Light/Dark/Auto modes
• added support for global border-radius override
• added support for overriding content and code font stacks
• added support for overriding builtin SVG icons
• added support for overriding component specific borders of the following elements
  • asides
  • badges
  • buttons
  • code listings
• added some new colors to make it easier to customize the follow elements:
  • buttons
  • documentation intro
  • tutorials overview page
• added support for customizing outer border radius of step elements
• all supported properties of the theme-settings.json file should be specified here (will open PR on Swift-DocC for this soon)

More documentation PRs will be created for the swift-docc repo next to guide users on how to utilize this file.

Dependencies

swiftlang/swift-docc#339 (already merged to Swift-DocC main)

Testing

Steps:

1. From this branch, run npm run build to build this branch of swift-docc-render
2. Checkout swift-docc and pull the latest main branch
3. Extract the example theme-settings.json file and custom article.svg icon from files.zip and copy them into the top level of the documentation catalog for SwiftDocC at Sources/SwiftDocC/SwiftDocC.docc
4. From the swift-docc repo, run env DOCC_HTML_DIR=/path/to/swift-docc-render/dist bin/preview-docs SwiftDocC
5. Open http://localhost:8000/documentation/swiftdocc and check that the theme settings are applied as expected
6. Play around with your own settings and check that there are no regressions if there are no theme settings provided

Checklist

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

• Added tests
• Ran npm test, and it succeeded
• Updated documentation if necessary

[mportiz08]

@swift-ci test

[dobromir-hristov]

Awesome work Marcus, just a few questions:

1. Would we keep the old --colors vs --color naming convention? I think --colors used to come from the initial version of the theme-settings? Or are we just deprecating that for now, without removing support?

[mportiz08]

Awesome work Marcus, just a few questions:

1. Would we keep the old --colors vs --color naming convention? I think --colors used to come from the initial version of the theme-settings? Or are we just deprecating that for now, without removing support?

From an API point of view, I think it should be considered unofficially deprecated. Since none of the implementation for it has been changed, things should continue to work if the plural form is used in the cases where it was previously being used, although ideally those clients using the old form could very simply adopt to the new version. Going forward, I think the singular form would be documented as the correct API. (I went with that version only because it has a 1-1 correlation with the actual CSS property names.)

[mportiz08]

I've opened a PR on DocC that adds an API reference for theme-settings.json and a conceptual article to walkthrough examples of using the file: swiftlang/swift-docc#359

[dobromir-hristov]

LGTM

[marinaaisa]

Thanks Marcus, this is a great improvement in the way we customise our UI 👏

[mportiz08]

@swift-ci test

[mportiz08]

@swift-ci test

[mportiz08]

@swift-ci test