RenderBlockContent.Aside Names

[patshaughnessy]

rdar://162549413

Summary

Introduce a new stored property on RenderBlockContent.Aside called name to store the name or title of aside blocks. This allows DocC to independently save and control the styling and the name of asides. Previously DocC conflated the style of the aside block (e.g. colors or other styling) with the name of the aside. Although it isn't currently possible to author an aside with a different style and name, this change allows the Aside model itself to support that one day.

Aside now has four available initializers:

• init(style: AsideStyle, content: [RenderBlockContent])
• init(name: String, content: [RenderBlockContent])
• init(style: AsideStyle, name: String, content: [RenderBlockContent])
• init(asideKind: Markdown.Aside.Kind, content: [RenderBlockContent])

Most often DocC will use the fourth initializer to create aside blocks from markdown, via RenderContentCompiler. This initializer, creating an aside from a Swift Markdown Aside.Kind, also contains special logic to determine a capitalized name for the aside that was previously implemented in AsideStyle.

Simplify the RenderBlockContent.AsideStyle structure to act as if it were an enum of the known styles supported by DocC Render: note, tip, experiment, important, or warning. (Since this is public API, this change retains AsideStyle as a structure with a string raw value.)

Also simplify the JSON encoding and decoding of the Aside and AsideStyle structures to save and read the style and name in a natural way.

The precise behaviors of each of the four initializers is listed and tested in SemaToRenderNodeTests.swift:

// The 5 standard styles are encoded and decoded. The names are set to the capitalized style name.
func testEncodingAsidesStandardStyles()

// The 5 standard styles can also be specified by name. The capitalization of the name is retained.
// The style is always lowercase.
func testEncodingAsidesStandardNames() 

// Unknown, custom styles are ignored and coerced to style="note" and name="Note"
func testEncodingAsideCustomStyles() 

// Custom names are supported using style="note"
func testEncodingAsideCustomNames()

// Custom names are supported using style="tip", by specifying both the style and name
func testEncodingTipAsideCustomNames() 

// Asides with a style matching a known kind of Swift Markdown aside are rendered using the display name of the
// Swift Markdown aside kind.
func testEncodingAsideKnownMarkdownKind()

// Asides with a custom/unknown Swift Markdown aside kind capitalize the aside kind to determine the name.
func testEncodingAsideUnknownMarkdownKind() 

Dependencies

None.

Testing

• Compile documentation that contains aside blocks, and ensure that DocC Render displays them properly.
• Deserialize existing Render JSON, adjust some aside blocks to have different style and name values, using init(style: AsideStyle, name: String, content: [RenderBlockContent]), serialize the Render JSON and test DocC Render displays the custom aside properly with the specified name and style. (Note this isn't currently possible to write using DocC markdown syntax.)

Checklist

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

• [x ] Added tests
• [x ] Ran the ./bin/test script and it succeeded
• [ ] Updated documentation if necessary

[patshaughnessy]

@swift-ci please test

[patshaughnessy]

@swift-ci please test

[mayaepps]

Looks good to me, I just left a couple comments.

[mayaepps]

Thanks for adding these comments!

[mayaepps]

I'm not sure I understand why this is - is it because it will be clearer whether the failure came from the aside name vs. style vs. contents? At first glance, it looks like this test is more complicated now to accommodate this.

[mayaepps]

Nit: this check looks redundant considering the two assertions below should catch if there are the wrong number of asides.