-
Notifications
You must be signed in to change notification settings - Fork 162
Do not emit variants for pages in article-only catalogs #241
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
franklinsch
merged 2 commits into
swiftlang:main
from
franklinsch:article-only-language-variants
Jun 9, 2022
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
20 changes: 20 additions & 0 deletions
20
Tests/SwiftDocCTests/Model/SemaToRenderNodeArticleOnlyCatalogTests.swift
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| /* | ||
| This source file is part of the Swift.org open source project | ||
|
|
||
| Copyright (c) 2022 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 XCTest | ||
| @testable import SwiftDocC | ||
|
|
||
| class SemaToRenderNodeArticleOnlyCatalogTests: XCTestCase { | ||
| func testDoesNotEmitVariantsForPagesInArticleOnlyCatalog() throws { | ||
| for renderNode in try renderNodeConsumer(for: "BundleWithTechnologyRoot").allRenderNodes() { | ||
| XCTAssertNil(renderNode.variants) | ||
| } | ||
| } | ||
| } |
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
111 changes: 111 additions & 0 deletions
111
Tests/SwiftDocCTests/TestRenderNodeOutputConsumer.swift
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,111 @@ | ||
| /* | ||
| This source file is part of the Swift.org open source project | ||
|
|
||
| Copyright (c) 2022 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 | ||
| @testable import SwiftDocC | ||
| import XCTest | ||
|
|
||
| class TestRenderNodeOutputConsumer: ConvertOutputConsumer { | ||
| var renderNodes = Synchronized<[RenderNode]>([]) | ||
|
|
||
| func consume(renderNode: RenderNode) throws { | ||
| renderNodes.sync { renderNodes in | ||
| renderNodes.append(renderNode) | ||
| } | ||
| } | ||
|
|
||
| func consume(problems: [Problem]) throws { } | ||
| func consume(assetsInBundle bundle: DocumentationBundle) throws { } | ||
| func consume(linkableElementSummaries: [LinkDestinationSummary]) throws { } | ||
| func consume(indexingRecords: [IndexingRecord]) throws { } | ||
| func consume(assets: [RenderReferenceType: [RenderReference]]) throws { } | ||
| func consume(benchmarks: Benchmark) throws { } | ||
| func consume(documentationCoverageInfo: [CoverageDataEntry]) throws { } | ||
| func consume(renderReferenceStore: RenderReferenceStore) throws { } | ||
| func consume(buildMetadata: BuildMetadata) throws { } | ||
| } | ||
|
|
||
| extension TestRenderNodeOutputConsumer { | ||
| func allRenderNodes() -> [RenderNode] { | ||
| renderNodes.sync { $0 } | ||
| } | ||
|
|
||
| func renderNodes(withInterfaceLanguages interfaceLanguages: Set<String>?) -> [RenderNode] { | ||
| renderNodes.sync { renderNodes in | ||
| renderNodes.filter { renderNode in | ||
| guard let interfaceLanguages = interfaceLanguages else { | ||
| // If there are no interface languages set, return the nodes with no variants. | ||
| return renderNode.variants == nil | ||
| } | ||
|
|
||
| guard let variants = renderNode.variants else { | ||
| return false | ||
| } | ||
|
|
||
| let actualInterfaceLanguages: [String] = variants.flatMap { variant in | ||
| variant.traits.compactMap { trait in | ||
| guard case .interfaceLanguage(let interfaceLanguage) = trait else { | ||
| return nil | ||
| } | ||
| return interfaceLanguage | ||
| } | ||
| } | ||
|
|
||
| return Set(actualInterfaceLanguages) == interfaceLanguages | ||
| } | ||
| } | ||
| } | ||
|
|
||
| func renderNode(withIdentifier identifier: String) throws -> RenderNode { | ||
| try renderNode(where: { renderNode in renderNode.metadata.externalID == identifier }) | ||
| } | ||
|
|
||
| func renderNode(withTitle title: String) throws -> RenderNode { | ||
| try renderNode(where: { renderNode in renderNode.metadata.title == title }) | ||
| } | ||
|
|
||
| func renderNode(where predicate: (RenderNode) -> Bool) throws -> RenderNode { | ||
| let renderNode = renderNodes.sync { renderNodes in | ||
| renderNodes.first { renderNode in | ||
| predicate(renderNode) | ||
| } | ||
| } | ||
|
|
||
| return try XCTUnwrap(renderNode) | ||
| } | ||
| } | ||
|
|
||
| extension XCTestCase { | ||
| func renderNodeConsumer( | ||
| for bundleName: String, | ||
| configureBundle: ((URL) throws -> Void)? = nil | ||
| ) throws -> TestRenderNodeOutputConsumer { | ||
| let (bundleURL, _, context) = try testBundleAndContext( | ||
| copying: bundleName, | ||
| configureBundle: configureBundle | ||
| ) | ||
|
|
||
| var converter = DocumentationConverter( | ||
| documentationBundleURL: bundleURL, | ||
| emitDigest: false, | ||
| documentationCoverageOptions: .noCoverage, | ||
| currentPlatforms: nil, | ||
| workspace: context.dataProvider as! DocumentationWorkspace, | ||
| context: context, | ||
| dataProvider: try LocalFileSystemDataProvider(rootURL: bundleURL), | ||
| bundleDiscoveryOptions: BundleDiscoveryOptions() | ||
| ) | ||
|
|
||
| let outputConsumer = TestRenderNodeOutputConsumer() | ||
| let (_, _) = try converter.convert(outputConsumer: outputConsumer) | ||
|
|
||
| return outputConsumer | ||
| } | ||
| } |
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm a little concerned about this scaling well in the future. Here's a few questions that came to mind- let me know what you think.
Should we consider just not emitting variants for documentation nodes that only contain a single variant? Is there a use case for the variant then?
Why are we only fixing this issue for TechnologyRoot catalogs? Should we fix this for any article that doesn't define a language?
In the future when we add support for articles with multi-language variants won't this break multi-language articles that are authored in TechnologyRoot catalogs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These are great questions!
This is still useful for renderers to know what language the page is available in for pages originating from frameworks, so that they can display e.g., "Language: Swift" or "Language: Objective-C" in the UI. From the render JSON perspective, the data is "correct", i.e., the page does have that variant. If we decide to not display the language information for single-variant pages, then I'd argue the change should be made in DocC Render, or at least controlled by a separate property in the JSON.
If associated with a module, articles inherit the module's languages, per #81.
If we add support for specifying what languages an article is available in, then yes, this logic will need to be updated and we'll likely want to implement a special
undefinedlanguage per #240. But I think we should consider these changes as part of that later fix. I'm also planning on cherry-picking this onto 5.7, so I'd like to minimize risk, and introducing a new specialundefinedlanguage would be a riskier change (e.g., we'd need to update the navigator index logic).There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That all seems reasonable to me. Thank you!