Add authoring support for a @PageColor directive

[ethan-kusters]

Bug/issue #, if applicable: rdar://106153042

Summary

Adds a new @PageColor metadata directive that allows for customizing the color used to represent a given page.

@PageColor gives authors control over the color used when rendering a page – initially this will affect the background color Swift-DocC-Render uses in the page's introduction (hero) section.

Example

# What's New in SlothCreator

@Metadata {
    @PageColor(blue)
}

![A sloth on a tree wearing a fedora.](sloth-fedora)

Let's check out what's new in SlothCreator!

...

Details

Declaration

@PageColor(_ color: Color)

Overview

Use the PageColor directive to provide a hint to the Swift-DocC renderer as to what color should represent this page. The renderer will use this color, depending on the context, as a foundation for the other accent colors used in the page. For example, Swift-DocC-Render will use this color as the primary background color of a page’s introduction section and adjust the colors of the icon and text in the page’s introduction accordingly.

This directive is only valid within an @Metadata directive.

@Metadata {
    @PageColor(purple)
}

Parameters

@PageColor accepts the following parameters:

• color: An unnamed parameter that accepts one of the following pre-defined colors. Each color is context-dependent.
  • blue
  • gray
  • green
  • orange
  • purple
  • red
  • yellow

Examples

The following screenshots show how Swift-DocC Render might interpret the given color inputs initially.

Forums post: https://forums.swift.org/t/support-for-customizing-a-page-s-accent-color-in-swift-docc/64093

Dependencies

• Allow customising the Intro section via PageColor swift-docc-render#582

Testing

Add @PageColor to the @Metadata directive in a Swift-DocC article or extension file and confirm that the resulting RenderNode includes a color metadata property.

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

[ethan-kusters]

@swift-ci please test

[ethan-kusters]

@swift-ci please test

[daniel-grumberg]

Maybe this should be a protocol and standard colors can then be an implementation of the protocol?

[daniel-grumberg]

Might be worth defining these somewhere more central and extending them to conform to DirectiveArgumentValueConvertible here. the advantage would be that we wouldn't have to stringify these values until render node encoding time.

[ethan-kusters]

I'd rather leave the RenderNode implementation more string-based for now until we have a better idea of how we'll implement longer-term support for custom page types. Our current needs are simple enough that I think we can prioritize flexibility here and reduce the risk of breaking API later on.

[d-ronnqvist]

Question: would a future custom color use a different property in the render json?

[ethan-kusters]

I think so – I wanted to give us the flexibility for that if we decide it's needed. My current thinking is that we'll likely have some kind of customColorReference here instead of a standard identifier.

[d-ronnqvist]

What are the default diagnostics for automatic directive convertibles when arguments are unknown or when multiple directives are specified, do we need to customize those?

For example

@Metadata {
  @PageColor(banana)
}

@Metadata {
  @PageColor(blue)
  @PageColor(green)
}

[ethan-kusters]

Those should both work:

/swift-docc/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md:7:5: warning: Duplicate 'PageColor' child directive
The 'Metadata' directive must have at most one 'PageColor' child directive

/swift-docc/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md:6:1: warning: Cannot convert 'banana' to type 'Color'

[d-ronnqvist]

This implementation looks good to me.

I left some non-blocking feedback about documentation and checking that diagnostic messages are good.

[mportiz08]

Not a blocker for this PR, but it would be awesome to update <doc:customizing-the-appearance-of-your-documentation-pages> article with an example of this new functionality.

[ethan-kusters]

Not a blocker for this PR, but it would be awesome to update <doc:customizing-the-appearance-of-your-documentation-pages> article with an example of this new functionality.

Good point! I filed #537 to track it.

[ethan-kusters]

@swift-ci please test

[moshe-foreflight]

Does this work with Tutorials?

[daniel-grumberg]

Does this work with Tutorials?

I am 99% sure it doesn't, Tutorial semantics are very different and this concept doesn't port cleanly over.