[GSoC 2025] Improved command line tool documentation

The notes don't perfectly capture the details I'm afraid, but there's also a fairly recent conversation we had in the DocC workgroup talking about options and tradeoffs in this space: Documentation Workgroup meeting: February 10th, 2025 - #2 by Joseph_Heck that's maybe worth a skim.

There's two paths - the existing one the plugin uses (make a file that, when added to a DocC catalog, renders nicely) and a deeper integration of converting the not-entirely-stable JSON format output from Swift Arg Parser into symbolgraph, the primary benefit of which is that it might be easier to reach for more custom-by-default rendering details (the icons embellishments for the page, linking of commands to option groups, etc). That said, nothing that I think David or I explored earlier couldn't be done as well with creative insertion of metadata directives into a markdown file that you dropped into a DocC catalog for later rendering.

2 Likes