Add @Image and @Video directives to reference documentation with caption support #381
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3 tasks
ethan-kusters
force-pushed
the
image-and-video
branch
from
118eac7
to
3aa1cd6
Compare
ethan-kusters
force-pushed
the
image-and-video
branch
2 times, most recently
from
57e28ad
to
fe0b43a
Compare
ethan-kusters
force-pushed
the
image-and-video
branch
3 times, most recently
from
a737dc5
to
01407b6
Compare
|
@swift-ci please test |
franklinsch
approved these changes
Oct 3, 2022
|
These changes look good to me. @Kyle-Ye I added you as a reviewer in case you want to take a look as well, since you've contributed to these areas in the past. |
Allows for other clients of image resolving to share this logic.
Currently we resolve and diagnose image references but include the `RenderInlineContent.image` regardless. This cleans up that behavior to only include it in the case where the image resolves.
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
Adding support for `@Image` in regular prose surfaced a bug in `@Volume` where the remainder was not being properly tracked after parsing the required `@Image` child in a `@Volume`. Instead the `@Image` stayed around in the general prose content leading to rendering issues now that we support `@Image` there.
ethan-kusters
force-pushed
the
image-and-video
branch
from
01407b6
to
7dadeae
Compare
|
@swift-ci please test |
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Bug/issue #, if applicable: rdar://97739628
Summary
Adds support for using the
@Imageand@Videodirectives from Tutorialsin regular reference documentation. This allows authors to
insert videos into documentation and to create images that have
attached captions.
To that point, the
@Imageand@Videodirectives can now containinline text to form a caption.
The final change here is that the
@Videodirective now supportsalt text.
Examples:
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
@Imagedirective swift-docc-render#404@Videodirective swift-docc-render#407Testing
Use
@Imageand@Videoin regular article content and confirm that work as expected.Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded