Documentation Workgroup meeting: September 9th, 2024

Swift Documentation Tooling Workgroup Updates
2

Documentation Workgroup Meeting 9 September, 2024

Requested Topics

  • (Sven) The recently announced multi target feature and if and when and how we could start testing that in SPI.
    • What toolchain would we need? 6.0? 6.1?
      • 6.0 has basic multi-target support
      • 6.1 adds the navigation element + overview page
    • Are there any special flag required to pass in via .spi.yml?
      • No, but we'll want to leverage the fact that now all targets are built by default
      • We'll need to update to use the new --target t1 --target t2 syntax
  • (Joe) The “Mentioned in” new/experimental feature that was recently added - generally what’s outstanding with it and taking it forward to “non-experimental”?
  • (Joe) Where should “documentation” updates go? In the case of Snippets, there isnt anything outside of the forums, and when I re-looked into the documentation for Docc it was heavily fractured between Docc itself and the docc-plugin.
    • Most specifically, where is most appropriate for snippets documentation to get created?
  • (Sofia) how we can improve DocC to better convey cross-platform availability.

Attendees

David Ronnqvist
Sofia Rodriquez Morales
Vera Mitchell
Joe Heck
Franklin Schrans
Daniel Grumberg
Sven
Dave Verwer
Kyle

Discussion

Franklin: Welcome Sofia! to the workgroup - official part of the workgroup now.

Multi-target docs

  • Sven: Is is ready to try out? SPI has a drop-down at the top to reference multiple docs, this seems to add on the side? What are the requirements to run this? Req toolchain? Flags needed?

  • David: most function with 6.0 toolchain. Combined navigation is in the 6.1 toolchain. 6.0 definitely has the start, uncertain how far you'll get. There is a new flag (--target flag), that takes a vector (list) of targets as options. When omitted, it builds every target in the package and merges it together.

  • Sven: when SPI triggers, --target is an option that SPI requires to opt-in to generating any docs. We're considering taking trigger and wrap it into this option

  • David: If that's getting used a lot, it may make sense to move to defaulting to product. (this default may not make sense for building internal documentation) If you merge mult targets w/ 6.0 toolchain, each will have seperate navigation. Navigation switches to local target. Combined nav is on 6.1 toolchain.

  • Franklin: regarding 6.1 combined navigation, what's the delta in experience?

  • David: In 6.0, You can intentionally write a link between targets, those become symbol links automatically. Clicking jumps to the other target, and the navigation "jumps" to the other target. Navigator focuses on one target at a time in 6.0. A general landing page doesn't exist with 6.0

  • Sven: SPI currently broken up across separate targets.
    Dave V: sounds like aiming to ship with 6.1 may have a better experience.

  • David: generally agreed - also navigation/quick-jump would search between all the relevant targets

  • David: there's another benefit to doing everyting in one plugin call, all base path, config/etc get passed to all relevant targets. Those wouldn't need to be updated across multiple configurations

Mentioned In

  • Joe: Is there something experimental about Mentioned In that we need to iron out?
  • David: I think it's marked experimental to give people a chance to try it out.

Documentation for documentation tooling

  • Joe: Where would be most appropriate to add documentation for Mentioned In or Snippets?
  • Vera: Probably makes sense in the DocC tool documentation (Documentation). We could have a page that outlines the experimental features, how to use them and what they do. That way, when they become official, we have a good basis for documentation.
  • Sofía: We also have other experimental features that are only discoverable through docc help.
  • Vera: I'd like to add docs for the overloads feature in that document.
  • David: Package plugin documentation should be more about package-specific concerns, rather than every flag that the plugin forwards to DocC.
  • David: Some aspects of snippets are worth discussing in both the DocC tool and plugin documentation.
  • Vera: The --skip-protocol-implementations is also somewhere in the middle, since it's a plugin flag that gets passed to the Swift compiler.
  • swift-docc/Sources/docc/DocCDocumentation.docc at main · swiftlang/swift-docc · GitHub <-- this one for the documentation repo

Cross platform availability

  • Sofia: how can we better convey cross-platform availability aspects within the documentation? I've drafted out a document with a list action items we can take we could take (DocC Availability Information for cross-paltform libraries - HackMD)

  • Joe: compiler availability indicates only minimum required swift/SDK platform version, doesn't include any sort of detail for "this is epxected - or NOT expected - to work" for each platform. SPI, for example, determines compatibility by building on each of the platforms (linux, Apple's devices through Xcodebuild)

  • David: The Info.plist that Sofia is talking about allows for specifying "unavailable" for a platform (for documentation-only purposes)

  • Sven: Difficult to test/isn't always a reliable indicator. Generally working well, but it's not tested/perfect. Certainly not eco-system wide.

  • Joe: windows build isn't yet supported anywhere for this sort of effort

  • Franklin: what actions should we take to promote this?

  • Sven: would like to have a "I expect this to work everywhere"

  • Vera: minimum version of swift a possibility, maybe scrape/look at swift-tools version, potentially using the same for swift-embedded.

  • Sven: tool version isn't always accurate

  • Sofia: Trying to guess right version is quite tricky - if they know/expect, best to assert it.
    Sofia: Next step (AI)- will open a forum post to discuss how to add to documentation, start to work out the details.

  • Joe: Embedded harder to make it work, so it'll potentially be important to folks

  • Franklin: I don't think there's an availability marker for "this works for embedded". Does SPI test for embedded?
    Sven: not today - we do build for linux and/or Apple platforms (xcode docbuild). SPI allows opt-in for specific means to build. Some symbols are only available on specific platforms. Is there any vision of how we should handle a multi-platform doc archive?

  • Sofia: if the symbol doesn't show in the availability for the platform?

  • Kyle: Can we have a multi OS chooser just like the version chooser on SPI?
    for example:
    • documentations
    • macos
    • linux
    • ios

  • David: It really boils down to compiler symbol generation - can't get the symbols for other platforms than the one you're building for. Example - iOS & Linux may have different flags. Would require first build for all the platforms, then merge them together... Docc can do that for macOS, tvOS, iOS, linux - but there's no built in way to wrangle that, since it requires builds for each platform.

  • Sven: is cross-compilation an option?

  • Joe: need the SDKs/toolchain for the platform

  • Franklin: if we build on different platforms, then it sounds like we can combine with Docc

  • Sofia: as long as symbols have same USR, it'll smoothly merge.

  • Franklin: some USR may be different - argument in one platform different from another.

  • Vera: may show duplicate symbols, which will result in multiple pages.

  • Franklin: workflow of combining symbolgraphs is something we do regularly at Apple, but it's not productized.

  • Sofia: will post to workgroup first - please contribute any feedback into draft hackMD or in forum post.

1 Like
Experimental Documentation Coverage
Pitch/Discussion - DocC feature discoverability and command-line documentation