mirror of
https://github.com/apple/swift-argument-parser.git
synced 2026-06-06 20:18:23 +00:00
Rauhul Varma
48a799e04a
- Adds a swift package manager command plugin called
GenerateManualPlugin. The plugin can be invoked from the command line
using `swift package experimental-generate-manual`. The plugin is
prefixed for now with "experimental-" to indicate it is not mature and
may see breaking changes to its CLI and output in the future. The
plugin can be can be used to generate a manual in MDoc syntax for any
swift-argument-parser tool that can be executed via
`tool --experimental-dump-info`.
- The plugin works by converting the `ToolInfoV0` structure from the
`ArgumentParserToolInfo` library into MDoc AST nodes using a custom
(SwiftUI-esk) result builder DSL. The MDoc AST is then lowered to a
string and written to disk.
- The MDoc AST included is not general purpose and doesn't represent the
true language exactly, so it is private to the underlying
`generate-manual` tool. In the future it would be interesting to
finish fleshing out this MDoc library and spin it out, however this is
not a priority.
- Next steps include:
- Improving the command line interface for the plugin.
- Adding support for "extended discussions" to Commands and exposing
this information in manuals.
- Further improve the escaping logic to properly escape MDoc macros
that might happen to appear in user's help strings.
- Ingesting external content a-la swift-docc so the entire tool
documentation does not need to be included in the binary itself.
- Bug fixes and addressing developer/user feedback.
Built with love,
@rauhul