Add support for `@Video` directive #407

dobromir-hristov · 2022-08-09T15:40:53Z

Bug/issue #, if applicable: 97715316

Summary

Add support for DocC @Video directive in Documentation pages.

Dependencies

This PR extends the work done the PRs below, and should be rebased after they are merged into main.

#404
#406

DocC PR - swiftlang/swift-docc#381

Testing

We need proper DocC support to be able to test this out, but you can add this JSON to the content of a random RenderJSON file from a doccarchive, and it should work:

Video JSON

                {
                  "type": "video",
                  "identifier": "video-reference.mp4",
                  "metadata": {
                    "abstract": [
                      {
                        "type": "text",
                        "text": "Video Caption"
                      }
                    ]
                  }
                }

Reference JSON inside references

    "video-reference.mp4": {
      "poster": "reference-to-poster-image",
      "type": "video",
      "identifier": "video-reference.mp4",
      "alt": null,
      "variants": [
        {
          "traits": [
            "1x",
            "light"
          ],
          "url": "/path/to/video.mp4"
        },
        {
          "traits": [
            "1x",
            "dark"
          ],
          "url": "/path/to/video~dark.mp4"
        }
      ]
    }

Steps:

Assert a replayable video is rendered with a "Play" button beneath it.
Assert Video can be rendered with a caption below it, but also without.

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

I think we should mark this PR as a draft until the two dependent PRs have been merged, and this has been rebased.

src/components/ContentNode.vue

dobromir-hristov · 2022-08-11T05:51:43Z

I think we should mark this PR as a draft until the two dependent PRs have been merged, and this has been rebased.

Yes, I just wanted to get things rolling.

dobromir-hristov · 2022-09-14T09:02:41Z

@swift-ci test

dobromir-hristov · 2022-09-14T09:06:46Z

@swift-ci test

mportiz08

Looks good and is working with the DocC branch.

My only minor concern is that the "Play" icon is the same icon as the "Replay" icon, which is a little bit odd. I would probably actually prefer that we just use the normal video controls and remove the play/replay link entirely, but you may want to discuss with the design team.

Also, make sure to rebase this against the main branch once the 3 dependent PRs have been merged (the replay one, the image one, and the figure caption one) before merging this one.

dobromir-hristov · 2022-09-15T06:56:38Z

@swift-ci test

dobromir-hristov · 2022-09-15T07:06:13Z

My only minor concern is that the "Play" icon is the same icon as the "Replay" icon

You have a point Marcus, I changed that because it's a good point anyway.

I will check with Design if they want me to just show full native controls all the time, instead of just on mobile devices. I think we discussed that we may want just the minimal UI of the tutorials.

dobromir-hristov · 2022-09-15T07:28:03Z

@swift-ci test

# Conflicts: # src/components/ContentNode.vue # tests/unit/components/ContentNode.spec.js

dobromir-hristov · 2022-09-15T08:13:42Z

@swift-ci test

dobromir-hristov · 2022-09-15T14:21:05Z

@swift-ci test

@image

Adds support for using the `@Image` and `@Video` directives from Tutorials in regular reference documentation. This allows authors to insert videos into documentation and to create images that have attached captions. To that point, the `@Image` and `@Video` directives can now contain inline text to form a caption. The final change here is that the `@Video` directive now supports alt text. Examples: @image( source: "overview-hero.png", alt: "An illustration of a sleeping sloth." ) { This is a caption adding additional context for the image. } @video( source: "sloth-smiling.mp4", poster: "happy-sloth-frame.png", alt: "A short video of a sloth jumping down from a branch.” ) { A *happy* sloth. 🦥 } This change is described on the Swift forums here: https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#image-1 Dependencies: - swiftlang/swift-docc-render#407 - swiftlang/swift-docc-render#404 Resolves rdar://97739628

@image

Adds support for using the `@Image` and `@Video` directives from Tutorials in regular reference documentation. This allows authors to insert videos into documentation and to create images that have attached captions. To that point, the `@Image` and `@Video` directives can now contain inline text to form a caption. The final change here is that the `@Video` directive now supports alt text. Examples: @image( source: "overview-hero.png", alt: "An illustration of a sleeping sloth." ) { This is a caption adding additional context for the image. } @video( source: "sloth-smiling.mp4", poster: "happy-sloth-frame.png", alt: "A short video of a sloth jumping down from a branch.” ) { A *happy* sloth. 🦥 } This change is described on the Swift forums here: https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#image-1 Dependencies: - swiftlang/swift-docc-render#407 - swiftlang/swift-docc-render#404 Resolves rdar://97739628

@image

Adds support for using the `@Image` and `@Video` directives from Tutorials in regular reference documentation. This allows authors to insert videos into documentation and to create images that have attached captions. To that point, the `@Image` and `@Video` directives can now contain inline text to form a caption. The final change here is that the `@Video` directive now supports alt text. Examples: @image(source: "overview-hero.png", alt: "An illustration of a sleeping sloth.") { This is a caption adding additional context for the image. } @video(source: "sloth-smiling.mp4", poster: "happy-sloth-frame.png", alt: "A short video of a sloth jumping down from a branch.") { A *happy* sloth. 🦥 } This change is described on the Swift forums here: https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#image-1 Dependencies: - swiftlang/swift-docc-render#407 - swiftlang/swift-docc-render#404 Resolves rdar://97739628

@image

Adds support for using the `@Image` and `@Video` directives from Tutorials in regular reference documentation. This allows authors to insert videos into documentation and to create images that have attached captions. To that point, the `@Image` and `@Video` directives can now contain inline text to form a caption. The final change here is that the `@Video` directive now supports alt text. Examples: @image(source: "overview-hero.png", alt: "An illustration of a sleeping sloth.") { This is a caption adding additional context for the image. } @video(source: "sloth-smiling.mp4", poster: "happy-sloth-frame.png", alt: "A short video of a sloth jumping down from a branch.") { A *happy* sloth. 🦥 } This change is described on the Swift forums here: https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#image-1 Dependencies: - swiftlang/swift-docc-render#407 - swiftlang/swift-docc-render#404 Resolves rdar://97739628

@image

Adds support for using the `@Image` and `@Video` directives from Tutorials in regular reference documentation. This allows authors to insert videos into documentation and to create images that have attached captions. To that point, the `@Image` and `@Video` directives can now contain inline text to form a caption. The final change here is that the `@Video` directive now supports alt text. Examples: @image(source: "overview-hero.png", alt: "An illustration of a sleeping sloth.") { This is a caption adding additional context for the image. } @video(source: "sloth-smiling.mp4", poster: "happy-sloth-frame.png", alt: "A short video of a sloth jumping down from a branch.") { A *happy* sloth. 🦥 } This change is described on the Swift forums here: https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#image-1 Dependencies: - swiftlang/swift-docc-render#407 - swiftlang/swift-docc-render#404 Resolves rdar://97739628

dobromir-hristov requested review from mportiz08, ethan-kusters, marinaaisa and hqhhuang August 9, 2022 15:40

mportiz08 self-assigned this Aug 9, 2022

mportiz08 reviewed Aug 10, 2022

View reviewed changes

src/components/ContentNode.vue Outdated Show resolved Hide resolved

src/components/ContentNode.vue Outdated Show resolved Hide resolved

dobromir-hristov marked this pull request as draft August 11, 2022 05:51

dobromir-hristov force-pushed the dhristov/r97715316-add-inline-video-support branch from e776478 to ccd67d2 Compare September 12, 2022 09:17

ethan-kusters mentioned this pull request Sep 13, 2022

Add @Image and @Video directives to reference documentation with caption support swiftlang/swift-docc#381

Merged

3 tasks

dobromir-hristov marked this pull request as ready for review September 14, 2022 09:02

mportiz08 approved these changes Sep 14, 2022

View reviewed changes

Dobromir Hristov added 4 commits September 15, 2022 09:55

feat: add support for @Video directive

a4cf728

chore: move Video to block type

2361a14

refactor: center captions that are below figures

3ebc903

refactor: rename InlineVideo.vue to BlockVideo.vue

05e58d3

dobromir-hristov force-pushed the dhristov/r97715316-add-inline-video-support branch from 95cabaf to 05e58d3 Compare September 15, 2022 06:56

refactor: use PlayIcon when ReplayableVideoAsset is not played yet.

a4ea377

Dobromir Hristov added 2 commits September 15, 2022 11:11

fix: bad test

50e5f5b

Merge branch 'main' into dhristov/r97715316-add-inline-video-support

1f0819a

# Conflicts: # src/components/ContentNode.vue # tests/unit/components/ContentNode.spec.js

Merge branch 'main' into dhristov/r97715316-add-inline-video-support

0622294

dobromir-hristov merged commit 3283805 into swiftlang:main Sep 15, 2022

dobromir-hristov deleted the dhristov/r97715316-add-inline-video-support branch September 15, 2022 14:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add support for `@Video` directive #407

Add support for `@Video` directive #407

Uh oh!

dobromir-hristov commented Aug 9, 2022 •

edited

Loading

Uh oh!

mportiz08 left a comment

Uh oh!

Uh oh!

Uh oh!

dobromir-hristov commented Aug 11, 2022

Uh oh!

dobromir-hristov commented Sep 14, 2022

Uh oh!

dobromir-hristov commented Sep 14, 2022

Uh oh!

mportiz08 left a comment

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

Uh oh!

Add support for @Video directive #407

Add support for @Video directive #407

Uh oh!

Conversation

dobromir-hristov commented Aug 9, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Dependencies

Testing

Checklist

Uh oh!

mportiz08 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dobromir-hristov commented Aug 11, 2022

Uh oh!

dobromir-hristov commented Sep 14, 2022

Uh oh!

dobromir-hristov commented Sep 14, 2022

Uh oh!

mportiz08 left a comment

Choose a reason for hiding this comment

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

dobromir-hristov commented Sep 15, 2022

Uh oh!

Uh oh!

Add support for `@Video` directive #407

Add support for `@Video` directive #407

dobromir-hristov commented Aug 9, 2022 •

edited

Loading