The Documentation Workgroup will be holding its next meeting on Monday, December 19th, 2022 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 page-turn review of TSPL
Feature enablement for quick navigation
Feature enablement for extension support
Please propose any additional agenda items in this thread.
KyleM: Posted GitHub issue/forum post for page-turn to make sure the content looks good.
All chapters have been reviewed. Alex has been putting up PRs to fix content issues.
Filed DocC Render bug when scrolling long pages, fix is in progress.
Missing copyright footer.
Kelvin: Updates on generating symbol graphs for standard library?
KyleM: No update yet. Alex can maybe provide details.
Victoria: There is a GitHub issue for it (Swift #61531).
KyleM: ETA on publishing new TSPL: around the time 5.8 ships (early next year). Need to look into redirects. More or less in a shippable state.
Franklin: Can mention in 5.8 announcement posts.
SofĂa: Not much of an update for quick navigation. Need to post forum post about enabling Quick Navigation by default. @marinaaisa and @beatriz have been working on UI updates.
Max: Ran into a few issues on the last PR on Windows so had to revert. No toolchain with the functionality yet to test. In discussion with SwiftPM team to get it merged ASAP. December 12 toolchain has the extensions support before it was reverted. I have swift-docc-plugin PRs as well and waiting for SwiftPM changes to land.
Daniel: Should we merge the swift-docc-plugin changes before we start the feature enablement discussion?
Max: It’s not required because of the plugin is in the toolchain, it’s configured separately in the package manifest.
Franklin: Will the PR enable extended types by default?
Max: Will depend on community discussion.
Daniel: Would suggest proposing enabling by default.
Max: Sounds good.
Ethan: Worried this is coming in a bit late. Maybe with flag in 5.8 and enable next release?
Max: I like that plan, especially since we’ve already branched for 5.8. Also worth noting this is be kept disabled by default at the Swift compiler level for non-documentation clients.
Daniel: Since the control of whether the feature is enabled is in the SwiftPM plugin, we’d still have control to disable the feature after the toolchain ships.
Franklin: Communication around that would be difficult.
Dan, Max, Ethan: Agreed.
Max: To recap, will have it off by default and introduce a non-experimental flag.
Sven: Could also start using this in SPI earlier than when it’s enabled by default in the next 5.8 release.
Ethan: Need to think about cases where locally users turned on the flag but SPI isn’t passing it, so the extensions will be missing. Maybe introduce a flag in the SPI yaml?
Sven: Agreed.
Franklin: Maybe this can be configured at the DocC level?
Ethan: Where this is configured is not obvious, SwiftPM level or DocC level?
Max: Configuration here is important because it affects the build and authoring environment.
Ethan: Need to define common configuration file.
Group agreed will keep configuration in SPI for now in the interim.
Dave: Fine for this case, but it would be better if this was independent of SPI.
Ethan: Maybe a config setting for “additional DocC flags” would be more flexible.
Dave/Daniel: Agreed, then any flag can go in there.
Foundation OSS
Franklin: Let's think of ways we can best support documentation regarding the recent Foundation announcement.
Holiday schedule: the group decided to skip the next workgroup meeting and meet on January 16th next.
KyleM: Should we talk a bit Mermaid since it was brought up again?
Victoria presented an overview of Mermaid
Ethan: Would be good to discuss diagramming needs, not sure if Mermaid is the right solution but we should consider supporting it regardless.
Franklin: Diagrams would help with showing your API’s architecture. Like the whiteboard test but in Markdown.
SofĂa: Need to discuss whether it’s the right choice to add the third party dependency.
Victoria: Other tools might be more appropriate. Could have an architecture where you plug in different formatters.
SofĂa: GraphViz could be an option. MermaidJS also supports UML.
SofĂa: Doing a university project on how we can use DocC to leverage diagrams.
Sven: Regarding multi-target support, we’re currently merging data folders. Is there a more sustainable solution we’re tracking?
Daniel: I’ll have a look.
Sven: Unrelated, sidebar is missing because there are no other pages.
Ethan: Should file a bug that if there are no children symbols, to disable the sidebar.
Sven: Case-insensitive handling
The documentation workgroup's next meeting will be on January 16th.
