- The name of "GenerateManualPlugin" was changed to "Generate Manual" to
improve the plugin's display name in Xcode. This however results in
the `.pluginWorkDirectory` provided by SPM to include a space (' ') in
the path. The space in the output path by itself is not a deal
breaker, but unfortunately `man` (at least on macOS) does not properly
handle path arguments with spaces. Example:
```shell
➜ swift package generate-manual
...
Generating manual for roll...
Generated manual in '.build/plugins/Generate Manual/outputs/roll'
...
➜ man '.build/plugins/Generate Manual/outputs/roll/roll.1'
/usr/bin/man: line 413: cd: .build/plugins/Generate: No such file or \
directory
```
IMO, easily previewing the generating manual takes precedence over the
UI in Xcode; as a result, this commit partially reverts the plugin's
name to "GenerateManual" to hopefully provide a good middle ground of
an output path without a space and a display name in Xcode that is a
little easier on the eyes than "GenerateManualPlugin" was.
- Removes the experimental prefix from the generate-manual plugin. The
manual generation still is not mature, but we would like to avoid
breaking adopters scripts by delaying changing the plugin's name in
the future.
`ArgumentParser` 1.1.3 includes a SwiftPM plugin for generating man
pages. However, this plugin is not visible to packages that declare
`ArgumentParser` as a package dependency.
Defining a product of type `plugin` in the package manifest will solve
that. Running `swift package plugin --list` for a package, that
declares `ArgumentParser` as a package dependency, will then list the
`GenerateManualPlugin`
```
‘experimental-generate-manual’ (plugin ‘GenerateManualPlugin’ in package ‘swift-argument-parser’)
```
Closes: #455
- 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
Nate Cook
Rauhul Varma
Clay Ellis
Marco Eidinger