I’m interested in the GSoC project idea “Improved documentation for command line tools” (Swift Argument Parser plugin + symbol graph + DocC). I plan to submit a proposal and would appreciate some guidance from mentors and the community.
I’ve read the existing discussion ([GSoC 2025] Improved command line tool documentation), including the scope around richer markdown vs. symbol graph generation and the option to prototype DocC enhancements that use the command symbol graph. I’d like to align my proposal with what’s feasible and most useful.
Could you share:
Any updated priorities or constraints for this project?
Suggestions for scoping (e.g. starting with markdown/plugin improvements vs. symbol graph first)?
Whether it would help to share a draft proposal here for feedback before the deadline?
I wanted to check if the following direction makes sense for the first phase of the project (richer markdown and configuration).
My plan is to group each command’s arguments into clear sections in the generated markdown, similar to how the CLI –-help output is structured.
if option groups are defined, I’ll reuse those so arguments appear under the same section titles as in the help text.
if no grouping is defined, I’d go to default sections like Arguments, Options, Flags, and Subcommands to keep the documentation consistent and readable.
Implementation plan i have is to make small PRs. first implement sectioning and grouping, second adding default/ allowed values to the markup, and 3rd possibly add more plugin configuration options
Does this align with what you had in mind for the “richer markdown and config” part, or would you prioritize something else first?
Happy to adjust the plan based on your feedback before locking it into the proposal.
this approach seems good to me, but the potential mentor mentioned on the site will give better opinions. you should share your complete proposal for review that will be better
Thank you, I appreciate it. Even a small suggestion or correction means a lot, I really think I have a good plan for this project idea, I basically love making UI better. And command is something that I use everyday.
On the tooling side, there haven't been any significant changes since the discussions from last year. I'm only aware of a few small tweaks to the markdown output.
So, while the priority of this project idea is largely the same as last year, there is now a key tool in the Swift ecosystem that publishes documentation about its command line interface based on this output. This means that any improvements that you do would be reflected on those pages.
My recommendations specifically for scoping a project like this—where there isn't a single larger feature or enhancement to implement—would be to pick and choose a combination of different improvements that you each think provide some value in a way that also makes sense, or "tell a cohesive story", in aggregate.
That has the benefit that you can more easily make incremental improvements and that it's easier to rescope if you find that it's going either faster or slower than what you initially expected/planned.
If you think about the benefits that you want to accomplish and work your way backwards to how to accomplish that then this can also make it easier to write up a proposal because you'll have more concrete goals to write about.
Another aspect to consider is your own learning for example by asking yourself "what do I want to have learnt after this?". Being aware of what you want to learn can help you identify which improvements you would find most motivating to work on and influence your pick of improvements.
One way to go about making this a bit more concrete—to have somewhere to start—could be to look at of the Swift Package command pages (for example the add-dependency subcommand and compare that to the corresponding help text. From this you can both note a number of differences; to name a few:
the page lists a large number of flags that the help text doesn't
the pages doesn't separate arguments and options into groups
flags like --type neither display their possible/allow values nor the default value
and you can try to ask yourself the question "what would I want to improve about this page"
Unfortunately that specific command doesn't organize its arguments and options into named groups so it can be useful to look at other tools and other commands as well to get a broader picture of the current state of the output and the possible improvements.
When it comes to knowing what improvements can be made in
the markdown alone
the markdown with generic symbol data
the markdown with custom symbol data
my top recommendation would be to ask if you're unsure.
For changes that you think could or couldn't be made to the markdown output alone you can also experiment by editing the markdown by hand and seeing how it renders. For example; you can include the --type options's possible/allowed values and its default value as text somewhere in its description and see if you find a location and formatting that you like.
For the differences between what could be accomplished with generic symbol data compared to custom symbol data I recently listed a few examples (in this post) about some of the things that structure symbol data could do for command line documentation.
If you have any questions about that or anything else, don't hesitate to ask.
Yes, if you can share a draft and get feedback on it that allows you to iterate on your proposal before submitting it.
I’ve created an initial version of my GSoC proposal for the “Improved Documentation for Command Line Tools” idea. It’s still a rough draft, and I’m sharing it mainly to get feedback on the overall approach and technical direction.
One thing I want to mention is that the timeline might not be optimal yet. I’m still learning how work is usually structured and reviewed in large Swift and Apple ecosystem projects. I expect that part to improve as I receive feedback. For now, my main goal is to confirm whether the implementation approach makes sense, especially the steps about improving the Markdown generation first and then adding a supplementary symbol graph for DocC.
I also haven’t built a prototype yet, so the proposal doesn’t have screenshots of generated documentation. I wanted to first confirm that the direction is reasonable before spending time building those examples. If anyone has time to take a look, I would really appreciate any feedback or criticism, especially from @ronnqvist.
Thanks for the detailed guidance. I’m still working through your suggestions, in particular, the SwiftPM add-dependency comparison and thinking about which improvements to pick and how to scope them.
I’ll complete and share an updated proposal once I’ve done that. but please take a look at the current approach.
I really like the usage of diagram, but creating the prototype for screenshot really necessary? you can just create codeblocks right? and you and merge some of the weeks to tighten the timeline table
thank you, i actually have been working on the diagram because it gives the idea how brainstorming will be directed. I have seen previous year proposals and may have added there prototype, i think i will make the sample anyways so codeblocks will not be needed.
the timeline will be my next priority after confirming the approach
I'll echo what Khushi said; you don't need to build a prototype to take screenshots.
If you want to include screenshots in the proposal I would recommend doing what's the least effort and least time consuming for you. Based on your preferences that could be anything from a mockup in an image editor or wire-framing tool, screenshots of pages where you modify the HTML by hand, formatted blocks of text inline in the document (with some visual distinction from the text that describes the proposal itself), a picture or scan of a pen and paper sketch, or anything else. If there are particular details of the design that you wanted to illustrate using screenshots you could also describe them in words if that's easier for you.
Prototyping can be valuable way to learn and/or explore a solution because it requires some amount of realism but you can get some of the same benefits by trying to think ahead and write down your solution as if you were explaining it to a friend or colleague. Writing down your plan for your own learning/thinking/exploration also has the benefit that you can reuse or rephrase much of what you write for the proposal.
A few comments on your draft so far.
1. In these two places you draw a possible connection (at least that's my understanding) between symbol graphs and having separate and linkable pages:
This proposal describes how I will implement [...], then integration with DocC for separate pages and linkability, [...]
Separate command pages and individual flag links - Integrate the symbol graph with Swift DocC to generate documentation with separate pages for each command and stable links for individual flags/options.
It's not wrong to write this and you're definitely not expected to have grasped subtleties of large systems that you've recently started looking at.
I just wanted to clarify—in case it has any impact on how you would plan the project or what you'd focus on—that you don't need the symbol graphs to have either separate pages or being able to link to pages. You could output one article per command or even one article per flag and, if you do, DocC would create a per command and flag and DocC would allow other markup to link to those "articles". Regardless if you have individual symbols or individual articles you'll need to break up the markup for each page.
2. Regarding the option group integration in DocC. I don't know if you'd need much custom integration here (if any). DocC already has markdown syntax for organizing pages into a hierarchy. This works with both symbols and articles. For more information, see the Arrange Top-Level Symbols Using Topic Groups section of the Adding Structure to Your Documentation Pages article in DocC's documentation.
3. I don't know if adding SymbolKit as a dependency would be an obstacle or not. This would be worth identifying early—by talking to the repo maintainers (I'm not one of them)—so that you know if you need to make any changes or implement some "backup" solution for that piece specifically.
4. I'll note that creating one page per flag has both benefits and drawbacks; if each flag mostly has one or two sentences of explanation/documentation then the output will contain a number of largely empty pages without significantly shortening the command's page (which would still list each flag so that readers can discover them).
This is a situation where different people may have different opinions (and different developer may want different behaviors for the command line tools). That could lead to a situation where you're asked to implement both behaviors (flags on the command page and flags as their own page) with a flag so that developers can specify which behavior they want. This is a slight risk of possible scope creep to be aware of.
A few different ways that you could get ahead of that possible scope creep is to:
include some time early on to start a Forum thread about flags as separate pages so that people can talk about it before you work on that code
plan to have some extra time set aside to implement that behavior in case you need that time
avoid the risk by not including that change in your proposal and treating it as a "future direction" / "future improvement" that someone (else?) could work on after this project has ended.
As a student, we can submit up to three proposals. I’m planning to use at least two of those for Swift-related projects. Would it be okay if I share both drafts in the thread (different threads) for feedback, or would you prefer reviewing only one?
For the Improved Documentation for Command Line Tools idea, is there any possibility that the scope could expand to a large project instead of medium, depending on the proposed work?
If I would be the potential mentor for both those projects or if I'd be in a topic where I can help then I'd be happy to look at the drafts. If there's another potential mentor for the other project then you may get better feedback from that person.
Yes, you can change the size of the project in your proposal. I intended for the "medium" size to be a rough guideline that students could use as a "constraint" to help them prioritize which improvements they want to focus on.
In other words; you can either use a "medium" size project and scope the project according to what you think is accomplishable in that timeframe or you can increase the scope and adjust the size of the project to how long you take to accomplish what you've included in the scope.
I do, in fact, would like to work on enhancing Swift DocC’s experimental documentation coverage feature as well. I saw last year’s proposal for the same and was intrigued by their approach. And I believe I will be able to learn a lot from that as well. I do wish to learn from both of the projects, and I am learning even while making the proposal.
I am not able to get what you meant by
I don't know if adding SymbolKit as a dependency would be an obstacle or not.
Should I try to get their idea on how the symbol kit can help?
So, I was assuming I had to use SymbolKit to generate a “symbol graph” as mentioned in the idea description. So there could be ways to skip adding a dependency and use a similar concept of graph here.
Yes, thank you, I do realise now that I was over-engineering it. Had I also seen last year’s proposal for this project, could I take some notes from that as well?
I will not be complicating things for if not necessary, I have a clearer structure for time aswell.
I would like to know if I should open an issue for the feature “displaying possible values and default values in usage strings and argument descriptions.” I think that is the best place to start with.
Thanks, that answers my doubt actually. “They“ were supposed to be the creators, maintainers, and users of SymbolKit. But since there are no external dependencies used, adding a dependency is a topic that requires discussion.
I will keep this in mind and update the proposal accordingly.
I’ve been exploring the hybrid approach for documenting CLI flags (keeping all flags on the command page, and only expanding complex ones), and I wanted to get your thoughts before going deeper into implementation.
Does this direction make sense to you as a baseline?
If yes, I’m planning to prototype a few variations to figure out what works best in practice. In particular, I want to experiment with different criteria for when a flag should move from inline to a separate detailed view (for example: length of description, presence of examples, complexity of behavior, etc.).
I’m also considering an approach where detailed descriptions are maintained in a central source and then pulled into separate views when needed, instead of creating many small files. Do you think that’s worth exploring, or would it go against how DocC is typically structured?
My goal here is to avoid the extreme you mentioned (too many fragmented pages which are mostly empty) and land on something practical and maintainable.
If you’re okay with this direction, I’ll set aside time in the working period to build a few prototypes and share them for comparison.
This idea isn't specific to only command line flags/arguments/options. If you look at many enumeration cases and properties on structures and classes you'll find a similar situation where many of the individual cases/properties don't have a much documentation on their own pages that isn't also displayed on the enumeration's/structure's/class's page (that displays the declaration and its abstract/summary).
Apple's developer used to display all members—both properties and methods—as expandable sections on the containing type page (a look and feel that's still used by Jazzy).
I think that it would be tricky (or hacky) to implement this behavior only for CLI flags/arguments/options. Instead it would be better to consider this as a possible general improvement for all DocC documentation. However, by my estimates that risks being much harder and much more to implement than all of the entire CLI documentation, so it would definitely be out of scope.
My previous comments about many small pages was more about the reader's experience browsing the documentation rather than about how the data is stored and fetched.
Still, for clarification, any idea that tries to implement some very custom behavior for CLI documentation that's not found elsewhere in DocC is going to significantly increase scope and the amount of up-front design discussion. It can be valuable to bring up the ideas to see if they'd make sense as general improvements but if they are included in your GSoC proposal I would think that they are more likely to hurt, rather than help, that proposal.
I will keep the implementation around what swift-docc already does for this part of the project then. we have to improve the UI of the output file that is basically ToolInfo JSON that is created by --experimental-dump-help.
And to display possible values and default values is a logical part which should be independent.
