Documentation Workgroup meeting: January 30th, 2023

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on Monday, January 30th, 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 feature enablement
  • Extensions support

Please propose any additional agenda items in this thread.

1 Like
2

I know this meeting has been and gone, but can I add something to the next meeting agenda? I think we should consider creating either a private or a public room on the recently consolidated Swift open-source Slack for better communication in between meetings.

6 Likes
3

Meeting Notes

Attendees

Notes

  • TSPL migration (KyleM)
    • Almost finished
    • Now using plain DocC catalog instead of package
    • Alex: Have guidance for folks. Dividing by the size of contribution. Have these ready to mention in the release/5.8.
    • Alex: Would be nice to have CI triggered builds.
    • Alex: Publishing trunk documentation on preview.
    • Kelvin: Discouraging linking to the preview?
    • Alex: Preview version has a big header at the top that explains that. Links you to the root of TSPL.
    • Kelvin: Would be nice to link you to equivalent page.
    • Alex: main is ready to ship, but not shipped yet.
    • Need to explore no-index attribute.
    • Also need to think about CI workflows.
    • Sven: SPI has issues where documentation isn’t published because there are plenty of versions
    • Dave: Can set up meta tag.
    • Alex: Would be nice if DocC had support for custom head tags.
  • Quick Navigation (SofĂ­a):
    • Merged Quick Navigation into 5.8 and trunk.
    • Franklin: Will a great space for future improvements
    • Franklin: When will it be in SPI?
    • Sven: Waiting for Xcode beta.
    • Sven/Dave: Will there be breakages with 5.8?
    • Alex: Riskier changes are under feature flags.
    • SofĂ­a: Would like to continue working on Quick Navigation to add a preview of documentation
  • Extension support (Max):
    • Posted about enablement, received positive feedback. Worked with Sven to run on Swift Package Index. No builds that failed with the new changes. Will worked Ethan to merge the swift-docc-plugin.
    • Joe: In testing, found more APIs that I didn’t realise I had.
    • Max: Not enabled by default.
    • Max: For versioning, release a new version of plugin.
    • Nate: What’s the SPI story?
    • Sven: Will extend the spi.yaml syntax to enable the feature.
    • Max: An “additional DocC plugin” flags would be more flexible.
    • Sven: Do we know the impact on archive size and file count?
    • Max: Will be one new page for symbol.
    • Max: In SPI, one package timeouted, but not sure if that was happening before.
    • Victoria: Same idea as publishing exported import documentation
    • Franklin: Documentation synonymous with library interface.
    • Kelvin: What if they do want to publish Foundation especially for linking?
    • Franklin: Mechanism exists today.
    • Franklin: What if you’re not running 5.8 and you depend on the new plugin?
    • Max: Will print a warning that you need new toolchain.
    • Daniel: Interesting to think about in the context of being default in the toolchain.
1 Like