Pitch/Discussion - DocC feature discoverability and command-line documentation

[Joseph_Heck]

As the 6.0 toolchain release was coming out, I noticed a few changes in the content output directly, and inquiring about them learned they were new options in DocC. I love the new capabilities, but also noted that such new capabilities were extremely undiscoverable.

We discussed the topic more generally about "where" you might add documentation to help address this situation in a recent docc workgroup meeting. From that, I've made a loose proof-of-concept pull-request to explore what it might look like to add in the docc CLI documentation, since that is where most of this detail is exposed.

My goal was making an initial proof of concept to both make features more discoverable and try to get Swift's CLI interface more exposed. It's especially rough in the case of docc today because even with the docc command itself is far more of a "driver" command. We've leaned into swift-docc-plugin to be a pleasant front-facing CLI interface. All the command-line options for docc are relevant for that plugin though, as that's where features are exposed.

All of the core content of the PR from the swift-argument-parser options, and I did a pass to put some loose DocC-ish article organization around it. I think a better evolved version of this would be generated entirely from the swift-argument-parser options content, potentially with a new SwiftPM command plugin, akin to what's available with generate-manual today.

Before going and tackling anything heavier, I wanted to open up a discussion, using what's there today as a baseline. The PR hosting this "first cut" is up and available now: DNM: Command docs proof-of-concept pitch by heckj · Pull Request #1030 · swiftlang/swift-docc · GitHub. I made a locally hosted GitHub pages copy of the content generated from these updates, visibly publicly for this discussion at Documentation

I personally find this kind of documentation valuable, more-so as Swift spreads into more hosted platforms. I looked through related projects, and the obvious comparison of Rust stood out with it's hosting of CLI documentation (cargo doc being a useful analog in this case).

I'm personally a little torn on if the argument-content by itself is sufficient, or if to really make it useful it should have a bit of description/expectation around it. What's encoded in the argument parser options is a bit more intentionally terse, and it seems that in a few cases, more exposition could add a lot of value.

I would appreciate folks taking a look, and most especially highlighting any other comparable works that should influence how we present this kind of detail and information. The obvious expansion would be to other prevalent swift-org CLI commands (swift package itself is a huge target, but there's also the recent advancement of swift format into the toolchain, although with a related discussion recently in the forums).

My own initial thoughts on this first pass:

• I wish I could mark up the title for the various articles I created with code-voice (backticks only show up as back-ticks, and don't change the formatting) so that it was a bit more clear it was a CLI command being documented.
• I'm thoroughly abusing Overview to what's output from swift-argument-parser as usage, and it feels awkward, although it does get the detail across. I suspect a separate article-style page that was explicitly more like a unix style man-page (troff) output might actually work a lot better.
• Some of the options are so opaque/internal language focused that it's not at all clear, even from docc cli help, why you would want to use them. I think a paragraph of exposition would alleviate almost all of the scenarios I spotted, but there's a really good question of where that content should live.
  • Since everything in here so far is coming from argument-parser options, I think there's a reasonable case for including it there, as long as it doesn't overwhelm the actual cli --help options - I haven't explored that yet.
  • There's also an argument in my head for treating the CLI arguments as a sort of "symbol" in it's own right, and using the existing DocC catalog structure to extend or provide more detail from what's in the arguments today.
• Beyond the obvious warts and styling that needs cleanup, the annotation of content was consistent enough that I feel confident that we could generate markdown output suitable for inclusion into a catalog reasonably effectively. How to flow that into a documentation build is good question. I first step could be a plugin that simply generates markdown content for inclusion into a docc catalog that automates the "markup tweaking" kinds of things I just did with this PR.

[j-f1 (Jed Fox)]

This is super cool and I would love to see this expanded to other command-line tools — it’s much easier on the eyes than a man page!

@Joseph_Heck

I wish I could mark up the title for the various articles I created with code-voice (backticks only show up as back-ticks, and don't change the formatting) so that it was a bit more clear it was a CLI command being documented.

I would argue that since all the other symbols (like type and function names) are also rendered in the regular text font, commands should not be an exception.

@Joseph_Heck

I'm thoroughly abusing Overview to what's output from swift-argument-parser as usage, and it feels awkward, although it does get the detail across. I suspect a separate article-style page that was explicitly more like a unix style man-page (troff) output might actually work a lot better.

To me, this output seems like the sort of thing that should go into the code block that shows the declaration of a symbol in regular API docs (specifically the one at the top that says @Redirected(from: URL) on this page), and the Overview should be reserved for a human-readable extended description of what the command does, just like we see with other kinds of API.

@Joseph_Heck

Since everything in here so far is coming from argument-parser options, I think there's a reasonable case for including it there, as long as it doesn't overwhelm the actual cli --help options - I haven't explored that yet.

Could you allow adding a doc comment to the actual argument declaration to provide content that replaces (or extends) the content provided via the API and shown in --help?

@Joseph_Heck

Beyond the obvious warts and styling that needs cleanup, the annotation of content was consistent enough that I feel confident that we could generate markdown output suitable for inclusion into a catalog reasonably effectively. How to flow that into a documentation build is good question. I first step could be a plugin that simply generates markdown content for inclusion into a docc catalog that automates the "markup tweaking" kinds of things I just did with this PR.

I’m definitely not the best person to comment on this, but from what I’ve seen previously, it seems like the best way to provide more structured data is by building a tool that outputs the symbol graph JSON format from SymbolKit, and then have DocC parse and convert that to a page. That way you don’t need to handle generating Markdown directly. This is definitely much more complex than generating the Markdown though and you’d probably need to extend the Symbol Graph spec a bit.

[ronnqvist (David Rönnqvist)]

I started exploring this in this PR back in February.

My idea was to start with something specific to DocC's CLI documentation and experiment and later take what I've learnt to turn it into something useful for other CLI's as well.

Since that first prototype I've started using the experimental --experimental-dump-help argument parser flag to extract the structured help data from the tool (not pushed to the PR yet).

Longer term I can imagine this becoming a command in the Swift DocC Plugin (since getting the input data would require interacting with the package manager to inspect the targets and their dependencies to know which are executables that depend on Swift Argument Parser).

[Joseph_Heck]

Looks wonderful David, obviously right along the same lines I ran into. Since the doc updates never got merged, where is this all standing? And more importantly, what can I (or others) do to help move this forward?

After having run through this manually myself, I can absolutely see where we don't want to be maintaining the content from arg-parser help in two places, as it will inevitably get out of sync and doubles the maintenance.

As it stands now, I'd really like to see the CLI docs included in docc. And I'd love to leverage the same process to help establish and maintain documentation for the other parts of the Swift toolchain (package-manager, format, test, build, et al), as that's standing out to me as an unfortunately wide gap for people getting started with Swift.

What can I do to help move Document the supported arguments, flags, and options for DocC's CLI by d-ronnqvist · Pull Request #837 · swiftlang/swift-docc · GitHub, or anything related, forward to make this capability solid within our ecosystem?