I’m a recent CS grad and I’m interested in joining GSoC for the first time with Swift! I’ve been interested in compilers and parsers recently, as well as CLI-based projects primarily in Python and Rust. I thought working on the Improved command line tool documentation project might be a good fit. I’m rather new to contributing to open source projects, so would just appreciate knowing if I’m on the right path to hit the ground running.
I currently have limited knowledge of Swift but I’m confident I can get a basic proficiency in short time as I enjoy learning new languages. I’m going to become more familiar with the argument parser code base by tracing tests and looking at good-first-issues once I’ve gained a little confidence.
I believe this project primarily involves enhancing the generate-docc-reference plugin from the project spec correct? I also see mention of using generate-manual as a sort of reference so I’ll also have a look at that. The symbol graph portion of the project sounds especially interesting so I'm excited to look more into that as well.
Happy to hear that you're interested in this project.
Correct. That plugin is what generates the command line documentation. There are several improvements that can be made to the output of that plugin command. For example:
The current output is all in one file (for example this test file) which leads it to render all on one page. That could be preferred for some tools, but other tools with more commands or commands with more options could prefer to display each command's documentation on its own page.
The output could organize each commands arguments, options, and flags under sections based on the command's option groups, just like the help text does on the command line. The help text also includes information about default values and possible allowed values that isn't included in the generated markup.
The output could utilize additional markup syntax to style text, display lists, etc. Both @Joseph_Heck and I did some previous explorations around what could look like (applied to the docc command line tool itself (here and here)
Yes, defining symbols for the commands and possibly also their arguments, flags, and options open up for a lot of interesting possibilities. Don't hesitate to reach out if you have any questions about symbol graph files or about how Swift-DocC reads and processes that information.
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.
Thank you both for further resources. I’ve had some time to explore a few things and I have a few questions that would guide my research further.
Is the goal of the project to both enhance the current plugin and implement the symbol graph version as an option for the plugin? The project description sounds like it's both, but as I read the workgroup meeting, general sentiment seems to make it sound like it’s one or the other. If it’s possible to accomplish the same end goal with both versions, is there a benefit to having both and not just the symbol graph generation? From what I understand, there’s some automatic behaviour there with SwiftDocC for linking etc.
I'm also curious about how SwiftDocC consumes the symbol graphs. I'm going to be looking into this next, but would appreciate anything important to watch out for. As far as I know, SwiftDocC uses the symbol graph generated by the Swift compiler, but are there any limitations when creating one ourselves? I'll be looking at this experiment by David in particular which seems to be in this direction.
Finally, I'm not quite sure what this final sentence in the project description is referring to: "If time allows, prototype some enhancement to command line documentation in Swift DocC that leverage the information from the command symbol graph file." Is this about modifying the SwiftDocC plugin to use this new symbol graph when generating package-level documentation?
The goal project is a little bit of both. Even with symbol information, the richer markdown output will be useful and the additional configuration to the plugin CLI itself will make the plugin work well with more projects of different sizes.
In that workgroup meeting we weren't always thinking about this as GSoC project but also as a project that could be implemented in smaller pieces over time—potentially by many different people—with incremental benefits with each iteration.
It's possible to scope this project up and down quite a lot. Without any symbol graph pieces it's probably closer to a "small" project and with too many symbol graph features it can easily grow to a "large" project or even more. Making some incremental enhancements could help with the scope because it's possible to reevaluate and size down the project if it feels like it's too short on time.
Only having symbols with minimal information defined already provide some very small enhancements, for example being able to display "Command" as the type of page, being able to use symbol links to refer to the commands, and being able to use documentation extension files to write additional documentation for each command. Beyond the minimal information, there are fields in the symbol graph that allow symbols to display different "names" in different places, that allow symbols to display a "declaration" with some amount of syntax highlighting. There are also relationships in the symbol graph file that could be use to associate commands and subcommands or associate flags with commands (if there are also symbols for the flags). In aggregate, a few of these fields start adding up to a small but meaningful enhancement over a markdown article. Regardless of how much symbol information you add, it becomes a foundation for other people to add to in the future.
The description for this project idea is primarily focused on changes to the Swift Argument Parser to enhance the plugin with more configuration and richer output. That final sentence is referring to also prototyping some changes in Swift DocC that utilize the new symbol graph information to do something custom for command line symbols that wouldn't already work out of the box (for all kinds of symbols).
Like I said above, it's possible to scale this project up a lot, so it's important to think about what's in scope and what's out of scope. You could go "wide" and add a more different pieces of command information to the symbol graph file but you could also go "deep" and only add a few pieces of information but also do something custom with that information in Swift DocC or Swift DocC Render. It's what you think would be most useful for the generated documentation about the command line tools.