Upstreams swiftly's generate-docs-plugin with minimal changes. Adds
tests against argument-parser's built in example tools.
The initial version of this tool is extremely minimal and should be
extended to output much more information contained in tool info, like
generate-manual does.
Cleans up some lingering odds and ends from #647. Specifically switches
CommandInfoV0 to use the old style description and updates
ArgumentInfoV0 to emit value descriptions as a separate dictionary.
Insert missing comma in targets array in Package.swift to fix Swift 5.7 build
break from commit 83c5134a24.
Replace 2 if expressions (which are not supported by Swift 5.7) that were added
to ToolInfo.swift by commit 83c5134a24.
Replace switch expression (which is not supported by Swift 5.7) that was added
to GenerateManual.swift by commit 44dd206a85.
Replace switch expression (which is not supported by Swift 5.7) that was added
to DumpHelpGenerationTests.swift by commit 83c5134a24.
Fixes#675
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
Since `ExpressibleByArgument` already maintains a list of
enumerable values for an argument, we can extend this to serve
as an ordered list for a new dictionary property that maps the
value name to its description, if applicable. The new property
is a static variable on `ExpressibleByArgument` labelled
`allValueDescriptions`.
If the description string for a value is the same as the value
string, it's assumed that the description is not implemented.
The new value strings are used in the help screen, in the
dump-help JSON output, and in the generated manual.
- adds check in single and multipage to leverage hidden description in
help dump to determine if the argument should be displayed
- adds check in argument synopsis to only display synopsis if not hidden
- updates existing tests that _had_ hidden output displayed in the
generate-manual output
These warnings are showing up in tests about types and protocols
that are defined within this package, so they don't pose a problem
for future library evolution. Instead of using the `@retroactive`
attribute, which isn't supported by older compilers, this change
fully qualifies the type and protocol in the relevant conformance
declarations, which suppresses the issue.
Re: https://github.com/apple/swift-evolution/blob/main/proposals/0364-retroactive-conformance-warning.md
- Fixes a bug where signle-page manuals did not include subcommand
abstracts because the DSL logic did not take to account root commands
vs subcommands. This change adds a "root" property to the DSL element
to allow for styling differences in the two cases.
- Changes the generate-manual --single-page argument to --multi-page, so
generate-manual with create a single manual page with all subcommand
information by default instead of many distinct files.
- Fixes an issue where the --author option was passed without its value
by the generate-manual plugin to the generate-manual tool resulting in
plugin invocation failures or incorrect author information.
- 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
Adds a new `AsyncParsableCommand` protocol, which provides a
`static func main() async` entry point and can call through to the root
command's or a subcommand's asynchronous `run()` method. For this
asynchronous execution, the root command must conform to `AsyncParsableCommand`,
but its subcommands can be a mix of asynchronous and synchronous commands.
Due to an issue in Swift 5.5, you can only use `@main` on an
`AsyncParsableCommand` root command starting in Swift 5.6.
This change also includes a workaround for clients that are using Swift 5.5.
Declare a separate type that conforms to `AsyncMainProtocol` and add the `@main`
attribute to that type.
```
@main enum Main: AsyncMain {
typealias Command = <#command#>
}
```
Rauhul Varma
Ross Goldberg
Bri Peticca
Joseph Heck
Nate Cook
Rauhul Varma
