Add @SupportedLanguage directive for articles

Adds support for the `@SupportedLanguage` directive, which can be used
in article files to indicate what languages an article is available in,
rather than using the languages that the module being documented is
available in.

rdar://102091191

Author: franklinsch

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -1789,9 +1789,9 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         articles.map { article in
             guard let (documentation, title) = DocumentationContext.documentationNodeAndTitle(
                 for: article,
-                
-                // Articles are available in the same languages the only root module is available in. If there is more
-                // than one module, we cannot determine what languages it's available in and default to Swift.
+                // By default, articles are available in the languages the module that's being documented
+                // is available in. It's possible to override that behavior using the `@SupportedLanguage`
+                // directive though; see its documentation for more details.
                 availableSourceLanguages: soleRootModuleReference.map { sourceLanguages(for: $0) },
                 kind: .article,
                 in: bundle
@@ -1839,6 +1839,19 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
         let path = NodeURLGenerator.pathForSemantic(article.value, source: article.source, bundle: bundle)
 
+        // Use the languages specified by the `@SupportedLanguage` directives if present.
+        let availableSourceLanguages = article.value
+            .metadata
+            .flatMap { metadata in
+                let languages = Set(
+                    metadata.supportedLanguages
+                        .map(\.language)
+                )
+                
+                return languages.isEmpty ? nil : languages
+            }
+        ?? availableSourceLanguages
+        
         // If available source languages are provided and it contains Swift, use Swift as the default language of
         // the article.
         let defaultSourceLanguage = defaultLanguage(in: availableSourceLanguages)

Sources/SwiftDocC/Model/SourceLanguage.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -133,6 +133,7 @@ public struct SourceLanguage: Hashable, Codable {
         id: "occ",
         idAliases: [
             "objective-c",
+            "objc",
             "c", // FIXME: DocC should display C as its own language (github.com/apple/swift-docc/issues/169).
         ],
         linkDisambiguationID: "c"

Sources/SwiftDocC/Semantics/Metadata/Metadata.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -26,6 +26,7 @@ import Markdown
 /// - ``CallToAction``
 /// - ``Availability``
 /// - ``PageKind``
+/// - ``SupportedLanguage``
 public final class Metadata: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
@@ -57,6 +58,9 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
     @ChildDirective
     var pageKind: PageKind? = nil
 
+    @ChildDirective(requirements: .zeroOrMore)
+    var supportedLanguages: [SupportedLanguage]
+    
     static var keyPaths: [String : AnyKeyPath] = [
         "documentationOptions"  : \Metadata._documentationOptions,
         "technologyRoot"        : \Metadata._technologyRoot,
@@ -66,6 +70,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
         "callToAction"          : \Metadata._callToAction,
         "availability"          : \Metadata._availability,
         "pageKind"              : \Metadata._pageKind,
+        "supportedLanguages"    : \Metadata._supportedLanguages,
     ]
 
     /// Creates a metadata object with a given markup, documentation extension, and technology root.

Sources/SwiftDocC/Semantics/Metadata/SupportedLanguage.swift

@@ -0,0 +1,58 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import Markdown
+
+/// A directive that controls what programming languages an article is available in.
+///
+/// By default, an article is available in the languages the module that's being documented is available in. Use
+/// this directive to override this behavior in a ``Metadata`` directive:
+///
+/// ```
+/// @Metadata {
+///     @SupportedLanguage(swift)
+///     @SupportedLanguage(objc)
+/// }
+/// ```
+///
+/// This directive supports any language identifier, but only the following are currently supported
+/// by Swift-DocC Render:
+///
+/// | Identifier                                 | Language               |
+/// | --------------------------------- | ----------------------|
+/// | `swift`                                | Swift                       |
+/// | `objc`, `objective-c`   | Objective-C            |
+public final class SupportedLanguage: Semantic, AutomaticDirectiveConvertible {
+    public let originalMarkup: BlockDirective
+    
+    /// A source language that this symbol is available in.
+    ///
+    /// For supported values, see ``SupportedLanguage``.
+    @DirectiveArgumentWrapped(
+        name: .unnamed,
+        parseArgument: { _, argumentValue in
+            SourceLanguage(knownLanguageIdentifier: argumentValue)
+                ?? SourceLanguage(id: argumentValue)
+        }
+    )
+    public var language: SourceLanguage
+    
+    static var keyPaths: [String : AnyKeyPath] = [
+        "language": \SupportedLanguage._language,
+    ]
+    
+    @available(*, deprecated,
+        message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'."
+    )
+    init(originalMarkup: BlockDirective) {
+        self.originalMarkup = originalMarkup
+    }
+}

Sources/SwiftDocC/Utility/MarkupExtensions/BlockDirectiveExtensions.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -40,6 +40,7 @@ extension BlockDirective {
         Stack.directiveName,
         Step.directiveName,
         Steps.directiveName,
+        SupportedLanguage.directiveName,
         Technology.directiveName,
         TechnologyRoot.directiveName,
         TechnologyRoot.directiveName,