Skip to content

Support beta status in navigator #1249

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

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

anferbui
Copy link
Contributor

@anferbui anferbui commented Jul 18, 2025

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

Summary

Currently DocC has some code in RenderIndex to be able to store whether a navigation item is beta or not, but the feature isn't supported yet:

// Currently Swift-DocC doesn't support marking a node as beta in the navigation index
// so we default to `false` here.
self.isBeta = false

This PR propagates beta information for both render nodes and external render nodes to the navigation index such that we can ultimately encode the information as part of the navigator (i.e. index.json file):

{
  "beta": true,
  "path": "/documentation/mykit/myclass",
  "title": "MyClass",
  "type": "class"
},

Same as in other parts of the codebase, an item is considered to be in beta if all of its platforms are in beta.

Navigator comparison (using swift-docc-render):

Before After
Screenshot 2025-07-18 at 10 23 50 Screenshot 2025-07-18 at 10 21 32

Dependencies

N/A

Testing

Previewed a custom bundle locally which contained both an external and local link which were both beta.

  • Verified that they showed the beta badge in the navigator when using swift-docc-render.
  • Verified that the resulting index.json looked as expected

Steps:

  1. Use example bundle: Example.docc.zip
  2. Set up a link resolver, e.g. using /path/to/swift-docc/bin/test-data-external-resolver and modifying the data as desired
  3. Run DOCC_LINK_RESOLVER_EXECUTABLE=/path/to/swift-docc/bin/test-data-external-resolver swift run docc preview --platform name=macOS,version=1.0.0,beta=true --platform name=watchOS,version=2.0.0,beta=true --platform name=tvOS,version=3.0.0,beta=true --platform name=iOS,version=4.0.0,beta=true --platform "name=Mac Catalyst,version=4.0.0,beta=true" --platform name=iPadOS,version=4.0.0,beta=true Example.docc
  4. Navigate to http://localhost:8080/documentation/mykit/myotherclass
  5. Verify that the index.json is showing the external reference as a node, and that the node has a property beta=true:
    {
      "beta": true,
      "path": "/documentation/mykit/myclass",
      "title": "MyClass",
      "type": "class"
    },
    [...]
    {
      "beta": true,
      "external": true,
      "path": "/resolved/path",
      "title": "Resolved Title",
      "type": "symbol"
   }

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

anferbui added 5 commits July 16, 2025 16:31
Adds a computed property to `NavigatorIndexableRenderMetadataRepresentation` which derives whether the navigator item `isBeta` or not. This uses the same logic used in other places in the codebase [1].

Fixes rdar://155521394.

[1]: https://github.com/swiftlang/swift-docc/blob/f968935b770b0011d7aa28f59eda22a8407282b7/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L592-L598
Propagates the `isBeta` property to the `NavigatorItem` type from `NavigatorIndexableRenderMetadataRepresentation`.  When we index a new node, whether the item is beta or not will now be captured as part of the navigator

This is preparatory work before this property is propagated to the `RenderIndex` [1].

Fixes rdar://155521394.

[1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift#L257-L259
The isBeta and isExternal properties weren't being serialised as part of `NavigatorItem`.

These properties are used to initialise to `RenderIndex.Node` during the conversion to `index.json` [1] and must be preserved when navigator indexes are written to disk [2] so that when they are read [3], we don't drop beta and external information.

This serialisation happens during the `finalize` step [4] and the deserialisation can be invoked via `NavigatorIndex.readNavigatorIndex` [5].

Otherwise, the values can be lost on serialisation roundtrip.

[1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift#L329
[2]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorTree.swift#L195
[3]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorTree.swift#L266
[4]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift#L1193
[5]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift#L157
All that was left was that on initialisation of a `RenderIndex.Node`, we propagate the `isBeta` value from the `NavigatorItem`.

With this change, beta information is now available in the navigator, encoded as `"beta": true` in the resulting `index.json` file.

Fixes rdar://155521394.
Update public documentation to add missing parameters
@anferbui
Copy link
Contributor Author

@swift-ci please test

@anferbui anferbui marked this pull request as ready for review July 18, 2025 09:49
@anferbui
Copy link
Contributor Author

@swift-ci please test

1 similar comment
@sofiaromorales
Copy link
Contributor

@swift-ci please test

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants