Just a quick update here: The initial support for the Navigator was merged to main this afternoon but will remain behind a feature flag as we continue iterating on it and discussing in this thread.
Here are some instructions if you're interested in trying it out locally with your own content:
Follow the instructions here to build and run the version of docc on main.
Clone the pre-built version of Swift-DocC-Render from the swift-docc-render-artifact repo with:
Thanks @Joseph_Heck! This is really great feedback from you and others.
We're using the navigator fragments emitted by the Swift compiler's symbol graph tool directly here, but per the symbol graph spec, the intention of the navigator fragments is to be optimized for scenarios with limited horizontal space so I think this is essentially a bug.
We actually have some inconsistencies here, for example, we don't include identifiers like struct and class but we do include func . I agree that the kind icons already convey this information so optimizing the experience to just include the symbol's name and (if applicable) arguments is likely what makes sense here.
We actually have some inconsistencies here, for example, we don't include identifiers like struct and class but we do include func . I agree that the kind icons already convey this information so optimizing the experience to just include the symbol's name and (if applicable) arguments is likely what makes sense here.
On this specific point: The rational for this choice was that some symbol kinds like structures and classes have specific icons, but many other symbol kinds share the same icon. Some examples (not sure this is exhaustive):
Functions (mutating or otherwise) and static functions use the icon [M]
Mutable and immutable properties both use [P]
static let members and and global variables (whether they're let or var) use [V]
Enumerations and enumeration cases both use [E]. Interestingly, enumerations don't get an enum prefix but cases do get a case prefix (presumably because it's obvious in context; cases are always children)
I don't have an opinion on what we should do—if anything—to address those cases.
I agree that hiding the sidebar should be optional, we should probably consider that improvement in the future across all viewports and not only for small/medium viewport sizes.
If you'd like to try out the sidebar with your own Swift Package, you can do the following:
Testing instructions:
Note that I'm going to use the Swift-DocC Plugin to simplify the instructions here but it's not actually required for this functionality. It just makes testing prerelease versions of the docc CLI a little more user-friendly.
for iOS using the DocC plugin in a package manifest, with Swift 5.6. (This is in the context of generating package documentation in the Swift Package Index.)
Following this discussion here I was wondering if there's a way to get the new sidebar with this setup or if we need to wait for some SPM/DocC release to get it automatically?
By default, the Swift-DocC plugin will generate an index of content that is useful for IDE’s, like Xcode, to render a navigator of all included documentation in the archive. Since this index isn’t relevant when hosting online, you can pass the --disable-indexing flag when generating documentation thats intended for an online host.
led me to believe this is something we'll want to set. But reading the discussion above about --index becoming the default I'm now wondering if this setting would prevent the sidebar from appearing even if we were using the proper DocC version that supported it.
Is this a parameter we should be setting for generated and hosted documentation?
The sidebar is included in Swift 5.7 Development toolchains on Swift.org here. In general both of the command-line invocations you provided look correct to me (it is correct to continue passing --disable-indexing even when you want the sidebar to be available on the web) and I'd expect them to "just work" once you update to a 5.7 toolchain.
If you'd like to continue using Swift 5.6 for building the actual source code, but use the Swift 5.7 version of Swift-DocC, you should be able to by passing a custom DocC executable path to your SwiftPM or xcodebuild invocation.
Assuming you have a recent 5.7 development toolchain installed but a version of Xcode with a 5.6 toolchain selected:
env DOCC_EXEC="/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin/docc" \
env DOCC_JSON_PRETTYPRINT="YES" \
swift package \
--allow-writing-to-directory "\(outputPath)" \
generate-documentation \
--disable-indexing \
--transform-for-static-hosting \ # <-- Note: This is optional with Swift 5.7 since the transformation is enabled by default.
--output-path "\(outputPath)" \
--hosting-base-path "\(hostingBasePath)" \
--target "\(target)"
And for iOS, you should be able to combine your two commands into one via the EXTRA_DOCC_FLAGS build setting.
Looks like this enabled for all Apple docs. Looks pretty nice. I did notice there's no control to hide it on most of these pages, even for things like release notes where the sidebar just shows older note. Can we get that control?
This is something that was brought up earlier in this thread and a feedback that we've seen come up few times already. I agree, this is definitely a feature we should consider making available for all screen size.
Is there a way to filter search results with symbol type? i.e. functions, instance methods, initializers etc. This would help narrow down the results where I know the type of result I am looking for.
