Generate web documentation with SAP

[rgoldberg]

Generate web documentation with SAP.

swift package --allow-writing-to-package-directory generate-docc-reference

Move documentation from README.md to SAP constructs in Swift command files.

[RintaroYamada]

Hi @rgoldberg,

I attempted to run swift package generate-docc-reference, but it seems the plugin is not currently configured in the project.
Also, I didn’t find any existing script in Scripts/ related to generating DocC documentation.

Would you prefer I integrate the Swift DocC Plugin into Package.swift, or do you have another approach in mind for generating the web documentation?

Thanks!

[rgoldberg]

@RintaroYamada The generate-docc-reference isn't Swift Argument Parser (SAP) 1.5.0; it's only in the SAP main branch.

I just merged a new PR into main that uses SAP's main branch, so please update your fork's main & pull that into your local main.

Then the following command line should work:

swift package --allow-writing-to-package-directory generate-docc-reference

The goal is to move all the command documentation from the README.md into the Swift files under Sources/mas/Commands in the appropriate SAP constructs (in CommandConfiguration or in attributes like @Argument).

Probably best to transfer the documentation as is from README.md to the appropriate places in Swift files, then redo the documentation if it's out of date, then rewrite the documentation to make it better, if necessary. Research what fields are used to generate the docs. I assume CommandConfiguration(abstract:) & the @Argument(help:) (the latter might require using ArgumentHelp(…)).

Let me know if you have other issues.

Thanks.

[rgoldberg]

@RintaroYamada You should probably watch all activity on this repo because I might frequently merge PRs into main, so you'll want to know when you might need to pull the new code.

[rgoldberg]

@RintaroYamada Also note that, hopefully, the same documentation can be used for the man pages that will be generated for #865. It should just be a different output for the same information, but maybe some different formatting will need to be applied. I don't know how formatting is applied for either documentation output.

[RintaroYamada]

@rgoldberg Thanks! I've updated the main file locally and started editing the relevant Swift files to document the commands in README.md with abstract: and help: fields.

I'll let you know if I run into any formatting issues between DocC and man page generation.

Thanks again for your guidance!

[rgoldberg]

@RintaroYamada No problem. Glad to help. Thanks for helping out.

Currently, I'm mainly working on cleaning up the private framework Objective-C headers, which I'll probably merge in soon.