add @Available directive for setting platform availability

[QuietMisdreavus]

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

Summary

This PR adds a new metadata directive: @Available. This can be used in articles and extension files to set platform availability for a documentation page. (When used in an extension, it overrides any information that came from the symbol itself.)

This directive was proposed in this forums thread: https://forums.swift.org/t/setting-a-documentation-article-s-platform-availability/61144

Note that while the thread proposed isBeta and isDeprecated arguments (and this PR parses them), they are currently not usable because of work that needs to happen in Swift-DocC-Render to support the behavior. The work in Swift-DocC is being tracked in #441.

Dependencies

None

Testing

Use the following Markdown as a test article:

# My Cool Article

@Metadata {
    @Available(macOS, introduced: "12.0")
}

This is a cool thing you can do.

Steps:

1. Add an article with the above markdown as Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/AvailableArticle.md.
2. bin/preview-docs
3. Ensure that "My Cool Article" shows "macOS 12.0+" in its page header:

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

[QuietMisdreavus]

@swift-ci Please test

[QuietMisdreavus]

@swift-ci Please test

[ethan-kusters]

Is there a reason to not just call this Availability? If so – I personally would lean towards AvailabilityMetadata. MetadataAvailability makes me think this affects the availability of the metadata.

[QuietMisdreavus]

I feel like the term "availability" is pretty overloaded already in the Swift-DocC codebase; there's already a SymbolGraph.Symbol.Availability in SymbolKit which could collide in the wrong situation, but SymbolKit also has AvailabilityItem docc itself adds AvailabilityRenderItem as well. AvailabilityMetadata seems like a fine enough rename; i could add that if you think the existing name is too confusing.

[QuietMisdreavus]

I think i want to keep the name, since my reasoning behind it is that it's "availability from the metadata", as opposed to "availability from the symbol" (SymbolGraph.Symbol.Availability). I would have nested the type declaration under Metadata, but the other Metadata directive types are also standalone so i decided to make it fit in with the others.

[ethan-kusters]

I would have nested the type declaration under Metadata, but the other Metadata directive types are also standalone so i decided to make it fit in with the others.

I agree with your initial thought here. My preference would be to nest this as an extension under Metadata – that fits in well with how the Row/Column and TabNavigator/Tab directives are structured today so we have some precedent at least and we could do the same with other commonly-named Metadata directives moving forward. (Eventually I'd like to split out directives into their own library so we don't run into these kind of collisions.) What do you think? My thinking is that it's more important to maintain the one-to-one relationship of container-class-API-name to directive-name relationship we currently have for the vast majority of directives.

[ethan-kusters]

I think i want to keep the name, since my reasoning behind it is that it's "availability from the metadata", as opposed to "availability from the symbol" (SymbolGraph.Symbol.Availability).

My objection to this is that I think a reasonable read of both of these is "availability for the metadata" and "availability for the symbol".

[QuietMisdreavus]

I think nesting the type under Metadata is the right move. I'll make the change.

[QuietMisdreavus]

@swift-ci Please test

[QuietMisdreavus]

@swift-ci Please test

[QuietMisdreavus]

@swift-ci Please test

[QuietMisdreavus]

@swift-ci Please test

[QuietMisdreavus]

@swift-ci Please test