Documentation Workgroup meeting: October 9th, 2023

[franklin (Franklin Schrans)]

The Documentation Workgroup will be holding its next meeting on Monday, October 9th, 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

• `convert` and `preview` commands crash on certain Markdown pages · Issue #678 · apple/swift-docc · GitHub
• Set `DOCC_EXTRACT_EXTENSION_SYMBOLS=NO` in doc builds · Issue #2651 · SwiftPackageIndex/SwiftPackageIndex-Server · GitHub

Please propose any additional agenda items in this thread.

[franklin (Franklin Schrans)]

Meeting notes

• `convert` and `preview` commands crash on certain Markdown pages · Issue #678 · apple/swift-docc · GitHub
  • David: issue with source ranges in diagnostics
  • We should disable for now while we resolve the issues. Can still enable it manually for testing.
• Set `DOCC_EXTRACT_EXTENSION_SYMBOLS=NO` in doc builds · Issue #2651 · SwiftPackageIndex/SwiftPackageIndex-Server · GitHub
  • David: Crash is very uncommon, leave enabled.
  • Sven: Regression from 5.9
  • Victoria: is there a way to query what packages aren’t able to build docs anymore?
  • Sven: We have a smoke testing suite.
  • David has a fix in 5.10: [5.10] Use `extensionTo` and `declaredIn` relationships to add extensions to path hierarchy by d-ronnqvist · Pull Request #727 · apple/swift-docc · GitHub
• Archive sizes: Sven to collect information about top packages so that we get more data to make an informed decision on disabling by default.
• Opened PR to show protocol info in synthesised symbol pages: When documenting members of extensions to external protocols, display the external protocol's name by patshaughnessy · Pull Request #732 · apple/swift-docc · GitHub
• Ethan: Have a few proposals, on docc init and overload symbols. Would be good for the group to review.
  • Sofia: Do feature flags go in DocC or DocC Render for the overloads support?
  • Ethan: DocC, Render JSON

[Genaro-Chris (Genaro Christian)]

Docc support for other formats like epub, pdf?

[Joseph_Heck]

@Genaro-Chris

Docc support for other formats like epub, pdf?

I wasn't sure if you're asking a question about Docc support for generating static outputs such as ePub or PDF, or proposing to talk about this at a future meeting.

[Genaro-Chris (Genaro Christian)]

Suggesting

[Joseph_Heck]

You’re certainly not the only one who’d like that. There’s an existing issue requesting it - Support an output format that doesn't require running on a server · Issue #354 · apple/swift-docc · GitHub - although I’m not aware of anyone yet starting on any implementation supporting that result as yet.

[Genaro-Chris (Genaro Christian)]

Is there any way I can help with that?