Add support for @Small directive #380

ethan-kusters · 2022-09-13T10:19:57Z

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

Summary

Adds support for the @Small directive as described here: https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#small-18

A new @Small directive based on HTML’s small tag. This directive can be used to specify small print like legal, license, or copyright text that should be rendered in a smaller font size.

@Small accepts no parameters and accepts arbitrary DocC markup body content.

Example:

You can create a sloth using the ``init(name:color:power:)``
initializer, or create randomly generated sloth using a
``SlothGenerator``:

   let slothGenerator = MySlothGenerator(seed: randomSeed())
   let habitat = Habitat(isHumid: false, isWarm: true)

   // ...

@Small {
    Licensed under Apache License v2.0 with Runtime Library Exception
}

Note
The implementation for @Small relies on some new infrastructure added in #378 to support directives that include directly renderable content.

Dependencies

Add support for @Small directive swift-docc-render#405

Testing

Using the latest version of Swift-DocC-Render (support for @Small landed on the main branch recently), build documentation for a DocC catalog that includes the @Small directive. Confirm it renders as expected.

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

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json

ethan-kusters · 2022-09-15T11:25:48Z

@swift-ci please test

daniel-grumberg · 2022-09-15T13:42:51Z

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -61,7 +61,11 @@ public enum RenderBlockContent: Equatable {
    /// A table that contains a list of row data.
    case table(Table)

+    /// A row in a grid-based layout system that describes a collection of columns.


Mega nit, this probably belongs in another patch.

Yeah agreed- I just missed it in #378 so I thought it was worth cleaning up here. I can split it into a separate commit though.

That would be nice

Split out here: e56bd43

daniel-grumberg · 2022-09-15T14:30:15Z

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json

+                "type": "object",
+                "required": [
+                    "type",
+                    "inlineContent",


Nit trailing comma

daniel-grumberg · 2022-09-15T14:31:57Z

Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift

@@ -1057,5 +1057,15 @@ class RenderNodeTranslatorTests: XCTestCase {
        XCTAssertEqual(row.columns.first?.content.count, 1)
        XCTAssertEqual(row.columns.last?.size, 5)
        XCTAssertEqual(row.columns.last?.content.count, 3)
+
+        guard case let .small(small) = discussion.content.last else {


Should we not have a separate test from row and column one for this? I find that having smaller test cases helps pin out failures faster.

Ah good catch- I meant to create a new one here. Should be fixed now. Thanks!

daniel-grumberg · 2022-09-15T14:32:40Z

Tests/SwiftDocCTests/Semantics/Reference/RowTests.swift

+        XCTAssertEqual(renderBlockContent.count, 1)
        XCTAssertEqual(
-            renderBlockContent,
+            renderBlockContent.first,


Should this not be in a separate patch?

Split into a separate commit here: e4a6fc4.

daniel-grumberg · 2022-09-15T14:41:47Z

Tests/SwiftDocCTests/Semantics/Reference/SmallTests.swift

+        }
+    }
+
+    func testMixesInlineAndBlockContent() throws {


Slight misnomer here, maybe something like testCanNotContainStructuredMarkup

daniel-grumberg · 2022-09-15T14:43:26Z

Looks pretty good to me, small fixes and then LGTM

The current tests only look at the `first` RenderBlockContentelement. This is a refactor to support testing `@Small` which can return multiple RenderBlockContent items.

@Small

Adds support for the `@Small` directive as described here: https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#small-18 A new `@Small` directive based on HTML’s small tag. This directive can be used to specify small print like legal, license, or copyright text that should be rendered in a smaller font size. `@Small` accepts no parameters and accepts inline DocC markup body content. Example: You can create a sloth using the ``init(name:color:power:)`` initializer, or create randomly generated sloth using a ``SlothGenerator``: let slothGenerator = MySlothGenerator(seed: randomSeed()) let habitat = Habitat(isHumid: false, isWarm: true) // ... @Small { Licensed under Apache License v2.0 with Runtime Library Exception } Dependencies: - swiftlang/swift-docc-render#405 Resolves rdar://97744845

ethan-kusters · 2022-09-16T08:19:49Z

@swift-ci please test

daniel-grumberg

LGTM

dobromir-hristov mentioned this pull request Sep 13, 2022

Add support for @Small directive swiftlang/swift-docc-render#405

Merged

3 tasks

mportiz08 reviewed Sep 13, 2022

View reviewed changes

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json Outdated Show resolved Hide resolved

ethan-kusters force-pushed the small branch from 1307077 to 1202a1d Compare September 14, 2022 13:25

ethan-kusters changed the base branch from row-and-column to main September 14, 2022 13:25

ethan-kusters force-pushed the small branch 3 times, most recently from cc6975e to 7c13a8e Compare September 15, 2022 11:25

ethan-kusters requested review from d-ronnqvist and daniel-grumberg September 15, 2022 11:25

ethan-kusters self-assigned this Sep 15, 2022

ethan-kusters marked this pull request as ready for review September 15, 2022 11:25

daniel-grumberg reviewed Sep 15, 2022

View reviewed changes

ethan-kusters added 2 commits September 16, 2022 09:17

Document RenderBlockContent.row

e56bd43

Refactor Row tests to consider all rendered block content

e4a6fc4

The current tests only look at the `first` RenderBlockContentelement. This is a refactor to support testing `@Small` which can return multiple RenderBlockContent items.

ethan-kusters force-pushed the small branch from 7c13a8e to cad3718 Compare September 16, 2022 08:17

ethan-kusters force-pushed the small branch from cad3718 to ec79942 Compare September 16, 2022 08:18

ethan-kusters requested a review from daniel-grumberg September 16, 2022 08:19

daniel-grumberg approved these changes Sep 16, 2022

View reviewed changes

ethan-kusters merged commit 5208c8d into swiftlang:main Sep 16, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add support for @Small directive #380

Add support for @Small directive #380

Uh oh!

ethan-kusters commented Sep 13, 2022 •

edited

Loading

Uh oh!

Uh oh!

ethan-kusters commented Sep 15, 2022

Uh oh!

daniel-grumberg Sep 15, 2022

Uh oh!

ethan-kusters Sep 15, 2022 •

edited

Loading

Uh oh!

daniel-grumberg Sep 15, 2022

Uh oh!

ethan-kusters Sep 16, 2022

Uh oh!

daniel-grumberg Sep 15, 2022

Uh oh!

daniel-grumberg Sep 15, 2022

Uh oh!

ethan-kusters Sep 16, 2022

Uh oh!

daniel-grumberg Sep 15, 2022

Uh oh!

ethan-kusters Sep 16, 2022

Uh oh!

daniel-grumberg Sep 15, 2022

Uh oh!

daniel-grumberg commented Sep 15, 2022

Uh oh!

ethan-kusters commented Sep 16, 2022

Uh oh!

daniel-grumberg left a comment

Uh oh!

Uh oh!

Add support for @Small directive #380

Add support for @Small directive #380

Uh oh!

Conversation

ethan-kusters commented Sep 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Dependencies

Testing

Checklist

Uh oh!

Uh oh!

ethan-kusters commented Sep 15, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethan-kusters Sep 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daniel-grumberg commented Sep 15, 2022

Uh oh!

ethan-kusters commented Sep 16, 2022

Uh oh!

daniel-grumberg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ethan-kusters commented Sep 13, 2022 •

edited

Loading

ethan-kusters Sep 15, 2022 •

edited

Loading