[GSoC 2026] Proposal Review: Improved documentation for command line tools

Development GSoC
1

Hello Swift Community,

I'm Anas, a senior CS student, and I'm applying for GSoC 2026 for the Improved Documentation for Command Line Tools project with @ronnqvist as the potential mentor.

I'd love to share my draft proposal and hear your feedback before the submission deadline. This is my first time applying for GSoC and posting here, so please bear with me if I make any mistakes! :nerd_face:

Overview:

Swift Argument Parser's generate-docc-reference plugin currently produces a single Markdown file for an entire CLI tool, no per-command pages, no flag grouping matching --help, and no structured representation DocC can reason about. Manually authored references like Swift Package Manager's command documentation show what good CLI docs look like, but maintaining them by hand is costly and they fall out of sync as commands evolve.

Goal:

The goal of this project is to improve the generate-docc-reference plugin in two incremental stages: first, producing richer Markdown output with one file per command and flags organized by @OptionGroup; second, generating a supplementary symbol graph file that enables the 'Command' page type, symbol links, and extension file support in DocC.

Deliverables:

  1. Richer Markdown output from the generate-docc-reference plugin

  2. Supplementary symbol graph file (.symbols.json)

  3. Tests and documentation

Proposed Modifications:

  1. Richer Markdown Output:

  • Per-command file splitting, one .md per ParsableCommand

  • Flag sections organized by @OptionGroup, matching --help layout

  • Default and possible values shown per flag

  • Snapshot tests validated against DocC's own convert command

  1. Symbol Graph Generation:

  • One symbol per command (swift.command) with stable identifier, display name, and abstract

  • memberOf relationships linking subcommands to their parent

  • Unit tests, no SymbolKit dependency

  1. Plugin Integration:

  • Both outputs integrated into the existing plugin workflow

  • End-to-end tests using SPM or DocC commands as real-world input

Full draft proposal: Google Docs.

Iā€™d appreciate any feedback on the direction, scope, or potential improvements.

Thank you!

1 Like