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)
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.