Rendernode spec fixes #1367
Closed
Rendernode spec fixes #1367
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
…ftlang#1230) * Don't omit "Type" suffix from disambiguation for Swift metatype parameters rdar://152496046 * Remove trailing commas for compatibility before Swift 6.1
…pe signature disambiguation (swiftlang#1231) * Fix issue where suggested link disambiguation removed leading and trailing parentheses for some closure types rdar://151311221 * Minor unrelated correction of whitespace in symbol declaration test data * Include more information in test failure messages about unknown disambiguation
…nts (swiftlang#1235) * Fix false positive curation for article links with extra path components rdar://150874238 * Remove explicit `.init` in test file * Remove unused variable in test * Add missing path separator in curator fallback code path
* External Render Node Support Created an `ExternalRenderNode` structure that represents a pseudo render node out of an externally resolved value. This structure contains the minimal information needed to hold a value that can be passed to the Navigator Index. Fixes rdar://146123573. Co-authored-by: Sofía Rodríguez <sofia_rodriguez@apple.com> * External Render Node representation for the navigator The structures `NavigatorExternalRenderNode` and `ExternalRenderNodeMetadataRepresentation` are meant to hold the information needed to add an external render node in the navigator index. Each of these contains the information of a external render node for a specific language variant, since things like the node title change depending on the selected variant. Fields which cannot be populated due to insufficient information have been documented. These can have varying effect on the resulting navigation node, particularly the navigator title. Fixes rdar://146123573. Co-authored-by: Sofía Rodríguez <sofia_rodriguez@apple.com> * Index external render nodes This method mimics the index method for render nodes [1] by indexing the main node representation, and the Objective-C representation. [1] https://github.com/swiftlang/swift-docc/blob/38ea39df14d0193f52900dbe54b7ae2be0abd856/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift\#L636 Fixes rdar://146123573. Co-authored-by: Sofía Rodríguez <sofia_rodriguez@apple.com> * Consume external render nodes During the convert process create the external render nodes from the context external cache and consume them to get them added into the navigator index. Fixes rdar://146123573. Co-authored-by: Sofía Rodríguez <sofia_rodriguez@apple.com> * Only add external nodes to index if manually curated in Topics section The NavigationIndex code has some logic about what to do with fallouts (i.e. nodes which are not curated anywhere). It places them at the top level of the navigator, so that they are not lost. This works well for render nodes, but for external render nodes, we don't want them to persist at the top level if they are not referenced anywhere. We'd like them to be excluded if not referenced. This can happen due to the fact that we consume **all** successfully resolved external entities for indexing, which includes external references in other sections of the page such as the Overview section, the abstract and the See also section. Fixes rdar://146123573. * Propagate isExternal value to RenderIndex Now that the `isExternal` property is populated as part of the `NavigatorItem`s, we can now use that value to propagate whether the node `isExternal` in the final `RenderIndex`, something which we couldn't support before. External nodes are now marked as "external": true in `index.json` as expected. Fixes rdar://146123573. --------- Co-authored-by: Sofía Rodríguez <sofia_rodriguez@apple.com>
…differences (swiftlang#1250) rdar://155975575
… ones (swiftlang#1252) rdar://155967920
…a missing domain (swiftlang#1256) RenderNodeTranslator.visitSymbol filters out availability items which have a missing or invalid domain (platform name). Swift developers can add global availability messages with no specific platform information, for example like this: @available(*, deprecated, message: """ Don't use this function; call some other function instead. """ ) In this scenario, the Swift compiler adds an availability item with the message but no domain (platform name) to the symbol graph file, like this: { "domain": null, "isUnconditionallyDeprecated": true, "message": "Don't use this function; call some other function instead." } To avoid displaying an empty/null platform in the DocC Render user interface, the RenderNodeTranslator needs to filter out these records. Additionally, AvailabilityRenderOrder.compare always returns false for availability items that have no name, leading to an unpredictable sort order when any of the items is missing a platform name, even for availability items that had a valid platform name.
… a SymbolGraph.Symbol (swiftlang#1253)
* Update DocumentationContext initializer to be async * Fix typo in test helper name * Fix inconsistent indentation in test code
…es (swiftlang#1261) * Add a utility to update the years in license comments of modified files * Move license updating utility to a dedicated sub directory * Use `Regex` instead of `NSRegularExpression`
…ng#1270) Co-authored-by: Joseph Heck <j_heck@apple.com>
With the new concurrency features in Swift 6, there are also a set of checks that ensure that the code is safe to run concurrently. Public static mutable variables are considered unsafe unless they are specifically of a type that conforms to `Sendable`. This patch changes the test bundle generation to use `let` instead of `var` in the case of `public static` properties.
* Remove no-longer-relevant `allTests` definition * Remove unused imports in tests * Pass unused `file` and `line` parameters in test helper * Remove unused `file` and `line` parameters from test helper * Remove two unused test helpers * Remove three unused properties in tests
…symbol-graph' tool (swiftlang#1275)
…comments (swiftlang#1277) * Add solutions to remove invalid metadata directives in documentation comments - Implement solutions for org.swift.docc.Metadata.Invalid<directive>InDocumentationComment diagnostics - Each invalid directive now has a solution that removes the directive - Follows the same pattern as other directive removal solutions in the codebase - Added comprehensive tests to verify solutions are provided correctly - Fixes issue swiftlang#1111 * Fix code duplication in validateForUseInDocumentationComment method - Create diagnostic once instead of duplicating it - Use conditional solutions array based on range availability - Single Problem creation path for better maintainability * Add range verification test for invalid metadata directive solutions - Verify replacement range matches problem's diagnostic range - Ensures solution targets the correct content - Improves test coverage for range accuracy * Move test comments into assertion messages for better clarity - Move explanatory comments into assertion message parameters - Provides better context when tests fail - Makes tests more self-documenting * Fix code duplication in validateForUseInDocumentationComment method - Create diagnostic once instead of duplicating it - Use conditional solutions array based on range availability - Single Problem creation path for better maintainability
swiftlang#1166) * Initial work on snippets documentation Co-authored-by: Joe Heck <heckj@mac.com> Co-authored-by: Jacob Hearst <jacob@hearst.dev> * consolidate copyright statements at bottom of markdown files and add a newline to the end of the file * enables Snippet directive code for documentation, and updates the generated symbolgraph with that change * updating with an overview * fixing license header for check script * Update Sources/docc/DocCDocumentation.docc/DocC Documentation.md Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Update Sources/docc/DocCDocumentation.docc/snippets.md Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Update Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * renaming article per feedback * update documentation to explicitly call out adding swift-docc-plugin dependency * Add an ASCII diagram of an example Swift package directory structure, to make it clear where the snippets go, and also where the documentation catalog goes. Also show a concrete example of how to reference a snippet. Fix a typo. * Include a full markdown example containing @snippet * applying updates based on David's feedback * co-locates snippet API ref content to source class rather than using an extension page * revising note about snippets vs. docc catalogs and target linkage * Update Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md Co-authored-by: David Rönnqvist <ronnqvist@apple.com> * removing section about markdown comments inside snippets * collapsing some of the demo material down per David's feedback --------- Co-authored-by: Jacob Hearst <jacob@hearst.dev> Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: David Rönnqvist <ronnqvist@apple.com>
* Delay removing the deprecated 'diagnostics.json file by 1 minor release * Keep old deprecated CLI flag for backwards compatibility * Remove API that was deprecated during the 6.1 release * Reduce duplication in updated test case * Simplify providing data to symbol graph loader * Remove unused API to remove nodes from path hierarchy
* Extract helper in `RenderNodeTranslatorTests` One of the test methods in `RenderNodeTranslatorTests` was duplicated multiple times. It has been extracted out of the tests and deduplicated. * Emit variants if any root module is a symbol When the render node translator visits articles, it emits variants for each language that the article is supported in. This step is skipped if an article-only catalog is being built, since it would otherwise lead to a redundant "Swift" language marker being rendered in the page. However, if a catalog contains more than one module, i.e. an article-only collection and a different module's symbol graph in the same catalog, then the variants are not emitted despite the possibility of the page being available in more than one language. This commit changes the boolean check to skip emitting variants only if all root modules are article-only. It does not affect the behaviour when building a correctly configured catalog that contains a sole root module. rdar://163926698
SwiftPM requires that all files within a target are accounted for as part of the build. If there are extraneous files that do not form a part of the target, the package manager emits a warning about unhandled files. This patch updates Package.swift to exclude all CMakeLists.txt files from their relevant SwiftPM targets to remove this warning.
…#1340) It should be either "Parameters:" (plural) with a nested list of named parameters, or "Parameter x:" (singular).
* Rename 'SwiftDocCUtilities' target to 'CommandLine' for clarity * Remove unnecessary prefix from 'SwiftDocCTestUtilities' target * Update library name in CMake files
This reverts commit d616aa5.
Add a workaround to repair the linker detection in CMake to allow testing properly in GHA based CI.
The navigation indexing code skips all further nodes after it has already indexed a node with a given identifier [1]. This can result in an odd interaction when there is an external link which is resolved to a path that the bundle serves itself (or more colloquially, a catalog has an external link to itself). Since external entities are indexed before local entities, they were always be preferred over local entities, resulting in local entities mistakenly being dropped from the navigator altogether. The resulting navigator is incorrect and missing nodes, due to external entities not having hierarchy information. This issue was introduced when support for external links in the navigator was introduced. This commit updates `ConvertActionConverter` to always index local entities first. If any external entities clash with local entities, they will be resolved as the local entity (including its hierarchy) in the navigator. Fixes rdar://163018922. [1]: https://github.com/swiftlang/swift-docc/blob/b27288dd99b0e2715ed1a2d5720cd0f23118c030/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift#L711-L713 [2]: swiftlang@65aaf92
The directory monitoring tests check for whether the documentation is rebuilt if the documentation catalog is edited when running a live server with `docc preview`. These tests assumed an extremely generous timeout for receiving the directory change signal, and ran much slower than the rest of the test suite. The timeouts have been reduced to a more reasonable threshold that succeeds even with throttled resources on a single-core machine.
* Add a public initializer to RenderContentMetadata * Update Sources/SwiftDocC/Model/Rendering/Content/RenderContentMetadata.swift Co-authored-by: David Rönnqvist <ronnqvist@apple.com> * Introduce PublicAPITests for verifying certain API are actually public. * Remove unneeded unit test in PublicAPITests.swift. --------- Co-authored-by: David Rönnqvist <ronnqvist@apple.com>
* Make CodableContentSection.section public This allows other applications linking to Swift DocC to access this property. * Modernize how section property initializes its stored property using an init accessor
…cs (swiftlang#1338) * Improve parsing of links with type disambiguation that include generics rdar://160232871 * Add documentation for the private type signature string scanner API
…endent module causes resolution failure (swiftlang#1327) * (swiftlang#1257) Combined module link issue - public extension of dependent module causes resolution failure * Apply suggestions from code review * Address feedback comments - Cleanup unrelated assertions - Use readable names for IDs - Cleanup unused IDs - Make sure the tests clearly show that relative paths resolve and absolute paths thoe 'no module' error - Use ExtendedModule name --------- Co-authored-by: Max Grebenets <mgrebenets@apple.com>
* Add missing fields in Equatable implementation The `Equatable` implementation of `LinkDestinationSummary` was missing some of the new fields which were added recently. This commit adds them. * Encode absolute presentation URL if present Support for absolute URLs in link summaries was added in 7db36ad. It added support for absolute URLs when decoding a link summary, but not when encoding it: https://github.com/swiftlang/swift-docc/blob/cfcd96f0e992af2287661f6a26e8398096f6bc1e/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift#L772-L773 https://github.com/swiftlang/swift-docc/blob/cfcd96f0e992af2287661f6a26e8398096f6bc1e/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift#L728 Both are needed when using an external link resolver, as the external link resolver needs to encode the entity to send to DocC. Fixes rdar://164628218.
* Extract the SourceLanguage type to a new "Common" target * Keep public type alias to moved SourceLanguage type * Use Swift 6 language mode in new target * Add "DocC" prefix to new common target
…iftlang#1239) * fixes OpenAPI spec mismatches between require properties and available properties * updating specs with feedback
The SwiftDocCUtilities directory was renamed to CommandLine, and then renamed again. When The second rename occurred, the file was not restored.
Since RenderIndex.Node’s type property is optional, the public initializer should accept an optional. Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com>
This updates some of the properties in the RenderNode tree to be mutable. A number of the top-level properties in RenderNode are already mutable, and making these additional properties mutable as well allows callers to modify these values. rdar://164748009
* Add test for API Collection icon rendering in external references Adds tests to verify that API Collections (articles with Topics sections) are correctly identified as .collectionGroup kind in linkable entities, ensuring cross-framework references display the correct icon. Includes regression test for explicit @pagekind(article) metadata override behavior to ensure the fix doesn't break existing functionality. The first test is temporarily skipped until the fix is implemented in the next commit. rdar://135837611 * Fix API Collection icon rendering for external references Ensures API Collections are correctly identified as collectionGroup kind in linkable entities by using DocumentationContentRenderer.roleForArticle logic. This fixes cross-framework references where API Collections were incorrectly showing Article icons instead of Collection Group icons. rdar://135837611
…ture use a new bit-set type for "sets" of languages (swiftlang#1355) * Implement SourceLanguage as a tiny identifier with properties stored separately This idea came from after realizing that in practice accesses are _almost_ exclusively `id`, `==`, or `<`. * Deprecate mutating SourceLanguage properties * Remove unnecessary custom language sorting * Avoid accessing the language ID where it's not necessary * Move "_TinySmallValueIntSet" to DocCCommon as "_FixedSizeBitSet" * Support different sizes of _FixedSizeBitSet * Add Collection conformance to _FixedSizeBitSet * Specialize a few common collection methods * Use masking shifts and overflow adds in other _FixedSizeBitSet implementations * Add a SmallSourceLanguageSet type * Rely only in `_id` comparison for known language sorting * Use new small language set type in link resolution code * Use new small language set type inside ResolvedTopicReference * Use new small language set type inside DocumentationDataVariantsTrait * Fix implementation code comments about direction for layout of values/bits * Add new source files to CMakeLists for Windows CI * User simpler parameter name for ResolvedTopicReference initializer * Update additional callers to prefer passing source languages rather than their string IDs * Misc minor code comment fixes and clarifications
rdar://159615046
…ntation gets published (swiftlang#1365)
Member
Author
|
I've got something whacky going on with the branch, I'm resetting this from scratch... |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
20 participants
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.
replaces #1364 - I caused some havoc with my own local branches and had to reset this.
Summary
Updates the OpenAPI spec declarations to match what DocC actually generates.
Dependencies
none
Testing
manually: Using a vendored version of these files, along with Swift OpenAPI generator, to create swift types and decode from two sample DocC repositories to verify the generated types.
Sources/DocCArchive/Vendoreddirectory of that projectChecklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded