Documentation Workgroup meeting: January 17th, 2023

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on January 17th, 2023 from 8:30am to 9:30am PT (or see the time in your own timezone).

This meeting will be open to anyone who wishes to contribute. If you wish to participate, please reach out to @swift-documentation-workgroup in forums via DM for a link to the WebEx meeting.

Meeting notes for this meeting will posted in this thread shortly after.

Agenda

  • Update on publishing staging TSPL
  • Quick Navigation
  • Extensions support

Please propose any additional agenda items in this thread.

2

With one of our goals for 2023 being improving the setup- and publishing-experience, I think it would make sense to start talking about our vision for the command line interface and the future of the DocC Package Plugin. In particular, I'd like to discuss the following points:

  • Do we need an initialize-documentation command?
  • How could a persisted configuration format look like that unifies configuration options for symbol graph generation as well as swift-docc? How would backwards-compatibility with swift-docc's Info.plist configuration file work?
  • (Necessity of) compatibility between and co-maintenance of the DocC Package Plugin and a toolchain-native documentation command to support packages with lower language version requirements.
2 Likes
3

Meeting notes

Attendees: @krilnon, @ethankusters, @marinaaisa, @franklin, @finestructure, @daveverwer, @daniel-grumberg, @ronnqvist, @theMomax, @sofiaromorales, @Joseph_Heck

Notes

  • TSPL (KyleM):

    • Very close to being ready, lots of cleanup thanks to community feedback.
    • Added copyright footer for published version.
    • Talked with Ethan about the structure of the book. Currently a Swift package but it could potentially be just a DocC catalog to make URLs more consistent. We can’t use Swift Package because we want to have spaces in the name of the module. With SwiftPM we get an underscore in the URL. Thought about a few Package manifest improvements opportunities for DocC.
    • Need to figure out with Mishal when to publish exactly. Alex to figure a plan in the next couple of weeks.

  • Quick Navigation (SofĂ­a):

    • Created forum post for feature enablement
    • Been fixing small bugs
    • DocC Render contributors have been making small fixes as well.
    • Marina: Have a PR open.
    • Franklin: Can these changes come later after feature enablement?
    • Marina: Will post approval in Swift Forums
    • Ethan: Is this for 5.8 or main?
    • SofĂ­a: 5.8 is reasonable. Well tested.

  • Extensions (Max):

    • Ready to make enablement post. Need someone with commit access to trigger toolchain to test on SPI to test in the next few days. Ethan will do that.
    • Will post on forums. Running on SPI will provide more guarantee that the feature (which is opt-in) works.
    • Sven: Will run documentation builds in SPI when the toolchain is ready and post results.
    • Should be ready by EOW.

  • Improving setup/publishing experience (Max)

    • Identified improvement opportunities for SwiftPM swift-docc plugin, I thought it could be a good opportunity to start talking about shipping in the plugin the toolchain.
    • Questions around what the future of the plugin would look like.
    • Ethan: From a technical perspective, land code in SwiftPM directly as a command, or get new infrastructure from SwiftPM to install plugins into SwiftPM by default. There is friction in people getting the documentation plugin set up and keeping it updated.
    • Max: Questions around compatibility; what if the package does specify the plugin in their manifest? How do we continue supporting this for packages using older tooling?
    • Ethan: Yes, interesting challenge.
    • Max: An ‘initialize-documentation’ command would be interesting. Would be helpful for other IDEs like VSCode and from the command line.
    • Ethan: It could be integrated in SwiftPM such that SwiftPM templates include documentation. Would be great to discuss this in Forums.
    • Ethan: Other opportunities of integration there. For example generating templates of Topics sections.
    • KyleM: Maybe some of this would live in DocC itself?
    • Ethan: Fair. Could be wrapped by other tools.
    • Max: Different topic; could unify the command line flags and Info.plist. You’d be able to customise symbol graph flags.
    • Ethan: Great use case for turning on documentation for internal documentation for example. Currently no place to specify that.
    • Franklin: Would be neat to have this in Swift Package manifests.
    • Ethan: Agreed. Would make it clear that DocC needs to be built into SwiftPM.
    • Franklin: Seems like we have more and more customisation points into SwiftPM.
    • Franklin: Would be interesting to prepare a Vision pitch, get aligned within this group, bring it to the community.
    • Ethan: Could interact with inter-target linking as well.
    • David: Should talk about the SwiftPM team as well. Maybe they already have ideas.