Document how to customize appearance of DocC docs

[mportiz08]

Bug/issue #, if applicable: 96977013

Summary

This adds an Open API reference specification for the theme-settings.json file and adds a new article to the DocCDocumentation.docc catalog titled "Customizing Your Documentation Appearance", which explains how the file can be used for theming purposes, with examples and screenshots.

Dependencies

Not an explicit dependency, but this work is synced to the implementation of the Swift-DocC-Render work in swiftlang/swift-docc-render#402

Testing

Run bin/preview-docs DocC to view the new article, and the new Open API spec file can be manually inspected.

Checklist

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

• Added tests (documentation changes only)
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[dobromir-hristov]

Hey Marcus, this looks great. ComicSans was a nice touch 😏

Can we add as section about Icons? I think those are quite cool and have a tricky moment we need to explain.

[mportiz08]

Hey Marcus, this looks great. ComicSans was a nice touch 😏

Can we add as section about Icons? I think those are quite cool and have a tricky moment we need to explain.

I completely forgot to write the section about icons, but I was planning on it. Thanks for the reminder!

[mportiz08]

Hey Marcus, this looks great. ComicSans was a nice touch 😏
Can we add as section about Icons? I think those are quite cool and have a tricky moment we need to explain.

I completely forgot to write the section about icons, but I was planning on it. Thanks for the reminder!

Added: 3ed0578

[franklinsch]

Looks great, thanks for putting this together! I have a few comments but generally this looks good to me.

[Kyle-Ye]

A small suggestion: This PR adds about 1MB's image file to the swift-docc repo which is not very friendly for developers with poor network status.

Could we change some of them with external links(Supported since #82)

Since currently, we do not support dark varients for external link images

Or compress the images first before committing them to git with some services like https://tinypng.com ? (Maybe we'll get only 100KB increase after doing the compression)

[Kyle-Ye]

A small suggestion: This PR adds about 1MB's image file to the swift-docc repo which is not very friendly for developers with poor network status.

Could we change some of them with external links(Supported since #82)

Since currently, we do not support dark varients for external link images

Or compress the images first before committing them to git with some services like tinypng.com ? (Maybe we'll get only 100KB increase after doing the compression)

After confirming the current status of swift-docc repo (swift-docc's Assets has about 15MB of image resources), I will take back my previous suggestion.

Based on the current status of picture resources size, I think this PR's increase is acceptable.

[mportiz08]

A small suggestion: This PR adds about 1MB's image file to the swift-docc repo which is not very friendly for developers with poor network status.
Could we change some of them with external links(Supported since #82)

Since currently, we do not support dark varients for external link images

Or compress the images first before committing them to git with some services like tinypng.com ? (Maybe we'll get only 100KB increase after doing the compression)

After confirming the current status of swift-docc repo (swift-docc's Assets has about 15MB of image resources), I will take back my previous suggestion.

Based on the current status of picture resources size, I think this PR's increase is acceptable.

Even if we merge this as-is soon, it may be good to look into possibly externalizing all of these assets in the future like you suggest. Thanks @Kyle-Ye!

[franklinsch]

@mportiz08 Any remaining work here before we merge?

[mportiz08]

@mportiz08 Any remaining work here before we merge?

No, but I'm hoping to time the merge along with the merge of the swift-docc-render implementation PR (which is also pretty much wrapped up, but we are doing more testing before merging).

[mportiz08]

@swift-ci test