Add page image directive #367
Conversation
ethan-kusters
force-pushed
the
add-page-image-directive
branch
4 times, most recently
from
08754b5 to
27c7011
Compare
|
@swift-ci please test |
1 similar comment
|
@swift-ci please test |
ethan-kusters
force-pushed
the
add-page-image-directive
branch
2 times, most recently
from
b16e565 to
2382375
Compare
| /// A basic XML parser that extracts the first `id` attribute found in the given SVG. | ||
| /// | ||
| /// This is a single-purpose tool and should not be used for general-purpose SVG parsing. | ||
| enum SVGIDExtractor { |
There was a problem hiding this comment.
In order to fully integrate with Swift-DocC-Render's theming system for custom icons, we need to be able to provide the id of any custom SVGs we're using as icons.
Asking the user to provide these would be unfortunate since it asks them to have a greater understanding of SVGs than they might have. So instead, this is a very basic SVG parser that just extracts the first id tag it finds. We're still asking the user to provide a valid SVG, but assuming they do provide a valid one, this will pull out the ID that DocC-Render needs.
There was a problem hiding this comment.
We should just make sure to point out in the docs that the <svg element of the icon needs some id. They can add with any code/text editor
There was a problem hiding this comment.
Yeah definitely. Having this well documented will be really important.
There was a problem hiding this comment.
Do we still need a warning when there's no ID?
There was a problem hiding this comment.
Also, what will happen if a custom SVG icon doesn't have an ID?
There was a problem hiding this comment.
rdar://99205219 tracks supporting rendering SVGs without IDs and other image types PNGs. SVGs with IDs will always be the best option since it allows DocC-Render to apply color tint and scaling more correctly but I'm still hoping we can provide a reasonable UX when those are not provided.
If we investigate more and that turns out to be unfeasible then we should add a warning here. So rdar://99205219 can track that eventuality as well if need be.
CC: @mportiz08
|
@swift-ci please test |
ethan-kusters
force-pushed
the
add-page-image-directive
branch
from
2382375 to
4480239
Compare
|
@swift-ci please test |
ethan-kusters
force-pushed
the
add-page-image-directive
branch
from
4480239 to
6d702ee
Compare
|
@swift-ci please test |
| /// A basic XML parser that extracts the first `id` attribute found in the given SVG. | ||
| /// | ||
| /// This is a single-purpose tool and should not be used for general-purpose SVG parsing. | ||
| enum SVGIDExtractor { |
There was a problem hiding this comment.
Do we still need a warning when there's no ID?
| @@ -172,18 +177,32 @@ public struct DataAsset: Codable { | |||
| /// depending on the system's appearance. | |||
| public var variants = [DataTraitCollection: URL]() | |||
|
|
|||
| /// The metadata associated with each variant. | |||
| public var metadata = [URL : Metadata]() | |||
There was a problem hiding this comment.
A data modeling question: What's the benefit of having metadata per variant instead of per asset? Would different variants of an SVG ever have different IDs?
There was a problem hiding this comment.
That's exactly the benefit: The ID is internal to the SVG and I think generally unknown to the developer/author so we can't depend on having the same ID per variant. I can imagine that in most cases the ID will be the same across variants but we can't depend on that without the potential of running into confusing breakage down the road.
Future metadata (maybe image size for a PNG?) - would also be variant (file) specific, not asset specific.
| @@ -210,6 +229,21 @@ public struct DataAsset: Codable { | |||
|
|
|||
| } | |||
|
|
|||
| extension DataAsset { | |||
| /// Metadata specific to this data asset. | |||
| public struct Metadata: Codable, Equatable { | |||
There was a problem hiding this comment.
I'm trying to imagine how we would grow/scale/expand this. Do we know of any other metadata that we plan on adding in the future? Is there going to be groups of applicable metadata per file type?
There was a problem hiding this comment.
I don't know of any at the moment. Maybe image size would be a reasonable addition in the future? Or maybe an image could be associated with a device frame via metadata?
In the actual JSON model I tried to make this as lightweight as possible (just an additional property in the variant), but here it seemed simpler and more ergonomic to introduce a wrapper struct.
| /// A basic XML parser that extracts the first `id` attribute found in the given SVG. | ||
| /// | ||
| /// This is a single-purpose tool and should not be used for general-purpose SVG parsing. | ||
| enum SVGIDExtractor { |
There was a problem hiding this comment.
Also, what will happen if a custom SVG icon doesn't have an ID?
|
@swift-ci please test macOS platform |
|
@swift-ci please test macOS platform |
|
@swift-ci please test |
ethan-kusters
force-pushed
the
add-page-image-directive
branch
from
6d702ee to
b9260f2
Compare
|
@swift-ci please test |
ethan-kusters
force-pushed
the
add-page-image-directive
branch
from
b9260f2 to
3c528c9
Compare
|
@swift-ci please test |
ethan-kusters
force-pushed
the
add-page-image-directive
branch
from
3c528c9 to
f0140c4
Compare
|
@swift-ci please test |
ethan-kusters
force-pushed
the
add-page-image-directive
branch
from
f0140c4 to
f7a515c
Compare
|
@swift-ci please test |
Adds a new `@PageImage` directive that can be placed inside a page’s
`@Metadata` directive block to allow for customizing the images that
will be used to represent the page in the navigator, hero, and elsewhere
in the UI.
For article-only catalogs it’s likely helpful to distinguish between
articles with custom icons- in the same way Swift-DocC has different
icons for different kinds of symbol pages.
`@PageImage` accepts the following parameters:
- purpose: The purpose of the image. One of the following:
- icon: This image should be used in place of wherever a generic
icon for the page would usually be rendered.
- card: This image should be used whenever rendering a card
representing this page.
- source: A string containing the name of an image in your DocC catalog.
- alt: (optional) A string containing a description of the image.
Example:
# Feeding a Sloth
@metadata {
@PageImage(purpose: icon, source: "leaf.svg", alt: "An icon representing a leaf.")
}
`@PageImage` is described on the Swift forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#pageimage-22
Dependencies:
- swiftlang/swift-docc-render#417
Resolves rdar://97739580
ethan-kusters
force-pushed
the
add-page-image-directive
branch
from
f7a515c to
0693f90
Compare
|
@swift-ci please test |
Bug/issue #, if applicable: rdar://97739580
Summary
Add support for an
@PageImagedirective that allows for customizing a given page's card or icon image.Dependencies
Testing
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded