Documentation Workgroup meeting: November 7th 2022

The Documentation Workgroup will be holding its next meeting on November 7th, 2022 from 9am to 10am 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

  • Documenting packages as a whole (with guest @FranzBusch from Swift on Server libraries)
  • Documentation extension support: dogfooding and onboarding (with guest @nnnnnnnn from Swift Standard Library addition libraries)
  • TSPL and Quick Navigation status updates
  • @Kyle-Ye: Discuss meeting schedule

Please propose any additional agenda items in this thread.

2 Likes

PT turns from GMT-7 to GMT-8 this Sunday. Which means it will start 1 hour later in a location where there is no Daylight Saving Time.

So it will be 1:00-2:00 in my timezone (GMT+8). Could we consider alternating one hour earlier in PT time? (Which means always pining it to GTM-7 9am)

1 Like

I've added this as an agenda item, thanks for bringing it up!

1 Like

For the TSPL updates, you can see a staging copy rendered out here: https://krilnon.github.io/swift-book/documentation/tspl/

Since last time, you might notice:

  • The language reference has an update presentation of grammar elements.
  • Chapters have their own abstracts, so the first paragraph isn't interpreted as an abstract.
  • Automatic see alsos are removed.
  • Chapters aren't badged as articles anymore.
  • A variety of updates to DocC and the book content mean that we build with no warnings now. *
  • Since I built this from a recent DocC, it also includes Quick Navigation.

* Although I think a recent commit introduced a couple warnings; we should probably turn on --warnings-as-errors as Kyle Ye suggested earlier.

2 Likes

Meeting Notes

Documentation Workgroup November 7th 2022

Attendees: @ethankusters, @franklin, @daniel-grumberg, @krilnon, @Kyle-Ye, @theMomax, @finestructure, @Alex_Martini, @daveverwer, @ronnqvist, @sofiaromorales, @daveverwer, @nnnnnnnn, @taylorswift, @scanon, @FranzBusch

Documenting extensions

  • Nate, Steve: Libraries that whose purpose is to extend the Standard Library will greatly benefit from DocC's new support for documenting extensions, for example swift-algorithms, swift-numerics, and swift-async-algorithms.
  • Max: Working on exposing the new feature through swift-driver so that it's easier to enable, ETA roughly 2 weeks.
  • Nate: Experimented with the feature in swift-algorithms and it's working very well. It would be nice to have link autocompletion support for extension APIs. Also, some curation improvements could be made, for example by default permutations(ofCount:) looks like it's curated directly underneath the top-level module page.
  • Max: Yes, I've noticed that as well. It would be nice to show more prominently the parent Collection type.
  • Nate: Along those lines, showing conditional constraints on the extension would be nice as well.
  • Kelvin: swiftinit places the parent type in the breadcrumbs of the page.

Support for prose-focused / book-like documentation

  • KyleM: Demo of staging TSPL website published using DocC. Used new DocC features to hide See Also sections, page eyebrows, and resolved all warnings.
  • Franz: This kind of documentation would be really great for SwiftNIO. The book format looks pretty much exactly how we want it. Currently have standalone Markdown files in the repository but they're unorganised and untracked, so collecting them into a DocC catalog makes complete sense. We've started an effort to write all new documentation, including long form, using DocC and the book format provides a great way to document NIO holistically rather than per-target. We also have a need of documenting concepts that span multiple repositories.
  • Franz: Vapor has switched documentation systems a few times and would also be a good candidate for the new DocC support. Will discuss further in the server workgroup.
  • Nate: swift-numerics as well.
  • Daniel / David: In addition to this, there is a longer term plan to support link resolution across targets, where you can link to symbols that are involved in the build graph (you can link to symbols from your modules' dependencies). In that model, narrative documentation would be a target that depends on all the other targets.
  • Ethan: swift-numerics exported-imports all its targets, so it's already possible to document all the targets' APIs together using DocC.

Publishing TSPL using DocC.

  • KyleM: Very close to publishing the staging version of TSPL to GitHub Pages under the swift-book repo.
  • Alex: We need to do a page-turn to check all the content. The staging website will make it easy for people to proofread and file issues.
  • In the next documentation workgroup meeting, KyleM and Alex will propose a plan to publish to swift.org.
  • KyleM will follow up with Dave and the website workgroup to understand what's involved in publishing to swift.org.

Quick Navigation

  • Sofía: Feature has been merged under feature flag.
  • Sven: Will enable that feature on the staging Swift Package Index website in the next few weeks for dogfooding. Will coordinate with Sofía.
  • Ethan: Should DocC expose a build flag to generate the theme-settings.json file to enable the feature?
  • Franklin: Would prefer not introduce a build flag if we can avoid it to avoid maintenance cost for the flag.
  • Nate: This feature looks really great. Are you planning on full text search as well at some point? For book-like content it would be great to have.
  • Sofía: Would be a good improvement in the future. There are performance and size implications. Searching the abstract makes sense as a first step.
  • KyleM: Being able to define custom metadata keywords would be a good addition as well.

Meeting time change

The workgroup decided to meet 30min earlier (8:30am PT) to better accommodate different timezones.

The next meeting of the documentation workgroup will be on December 5th, since on November 21st lots of the workgroup members will observe a Thanksgiving holiday.

Action items

  • Max: Collect remaining work items for extension support, e.g., into GitHub Issues.
  • KyleM: Publish staging TSPL on GitHub Pages and send a Forums post on behalf of the documentation workgroup to get eyes on it.
  • KyleM / Alex / Dave: Prepare plan to publish DocC-based TSPL to swift.org.
  • Sofía / Sven: Enable Quick Navigation on staging Swift Package Index.
5 Likes

Ahhh! Great!

Super.

Thanks to all involved!

…As a sidenote, let me add a hint to a feature of the Swift Package Manager that might not be widely known:

Get a visual presentation of the package dependencies for a package via:

  1. swift package show-dependencies --format dot >deps.gv
  2. dot -Tpng deps.gv >deps.png (dot being a command of Graphviz)

Maybe such an output could be integrated into DocC (maybe the SVG output of dot)?

1 Like

Here's the overview of remaining work items for extension support: [SR-15410] Can't document extensions with DocC · Issue #210 · apple/swift-docc · GitHub

1 Like