Add support for the @Image directive
#404
Merged
Conversation
This file contains hidden or 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
…tract, but not anchor. use the `metadata.title` to determine if a figure caption should be above/below the content
dobromir-hristov
requested review from
mportiz08,
ethan-kusters,
marinaaisa and
hqhhuang
3 tasks
mportiz08
reviewed
Aug 9, 2022
3 tasks
mportiz08
approved these changes
Sep 13, 2022
There was a problem hiding this comment.
Tested with the DocC branch and looks good (no actual spec changes needed for the image specifically it seems).
The only potential issue I noticed is that the proposal for this new directive showed examples where the caption text is centered underneath the image as opposed to left aligned as it is now. If we were to support that, we may need to update the directive itself to allow for both alignments (because we already support the left aligned ones for older content).
That is a great observation Marcus. We can do this actually, because we can assume that captions with titles are always above the figures and left aligned, where as ones without a title are below and centered. I did the change on the Video PR as I assumed we may just use that one, since docc also combined the two features into one - 6c58c84 |
|
@swift-ci test |
dobromir-hristov
deleted the
dhristov/r97715120-support-figcaption-position
branch
ethan-kusters
added a commit
to ethan-kusters/swift-docc
that referenced
this pull request
Sep 30, 2022
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
ethan-kusters
added a commit
to ethan-kusters/swift-docc
that referenced
this pull request
Sep 30, 2022
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
ethan-kusters
added a commit
to ethan-kusters/swift-docc
that referenced
this pull request
Oct 1, 2022
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
ethan-kusters
added a commit
to ethan-kusters/swift-docc
that referenced
this pull request
Oct 3, 2022
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
ethan-kusters
added a commit
to swiftlang/swift-docc
that referenced
this pull request
Oct 3, 2022
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
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: 97715120
Summary
Extends support for the
@Imagedirective, by allowing users to add captions to images.It uses the already available
InlineImagecomponent, and just extends theFigurelogic to wrap, if either ananchororabstractis present.Dependencies
DocC PR -
Testing
You can add this RenderJSON piece to the
contentarray of your render jsonprimaryContentSections:{ "type": "image", "identifier": "reference-for-image", "metadata": { "abstract": [ { "type": "text", "text": "Image Caption" } ] } }Or use the attached JSON:
example_image.json.zip
Steps:
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
npm test, and it succeeded