Add experimental manual page generation #332
Conversation
Package.swift
Outdated
| name: "roll", | ||
| dependencies: ["ArgumentParser"], | ||
| path: "Examples/roll"), | ||
| name: "MDoc", |
There was a problem hiding this comment.
Maybe I should fold this into ArgumentParserGenerators
|
@tomerd do you have any ideas on if/how this could work the spm plugin stuff? |
|
I think splitting out completion script / man page generation to a separate tool would be nice for code size (given the other case about that). Also, are you thinking of DocC style comments inline with the code for the actual man page content? It would be nice if the same syntax could be used? |
|
I assume the desired behavior here would be to create a custom command such as |
I'm not exactly sure what the desired UX is, but I think it would be nice to build a package for distribution which would mean creating a layout maybe like this: package
├── bin
├── lib
└── shareThis would be a nice foil to "spm install" which maybe could install any package that is buildable for distribution. Thoughts? |
I think this would be an excellent future addition, but probably not as inline comments, but instead in the additional articles/tutorials format the DocC supports! |
That would be awesome. |
|
@rauhul with swiftpm commands plugins now in place, would be interesting to revisit integration options |
|
@tomerd I gave a plugin a shot, but I wasn't sure how to fit all the pieces together. Would you mind taking a look at the approach in the most recent commit? |
|
@swift-ci please test |
1 similar comment
|
@swift-ci please test |
rauhul
changed the title
|
@swift-ci please test |
- 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
|
@swift-ci please test |
There was a problem hiding this comment.
This is great stuff, @rauhul! 👏 👏 We do need to add a test harness as a follow-up so that we can make sure we're not breaking this plug-in as we move forward.
|
@swift-ci Please test |
|
@swift-ci Please test |
* 'main' of github.com:apple/swift-argument-parser: (114 commits) Fix `AsyncParseableCommand` hierarchy (apple#436) Add experimental manual page generation (apple#332) Improving edit distance string extension (apple#446) List valid options in error messages for enum array argument (apple#445) Remove LinuxMain.swift (apple#367) Hide hidden subcommands from completions (apple#443) Update changelog for 1.1.2 release (apple#441) Fix error message for @option array without values (apple#435) Fix Repeat's endless printing (apple#437) build: statically link ArgumentParserToolInfo always (apple#424) Update changelog for the 1.1.1 release (apple#428) build: complete the changes from apple#423 (apple#425) Remove platform requirement from Package.swift (apple#427) build: repair the build after apple#404 (apple#423) Fix broken links/incorrect variance calculation (apple#422) Update changelog for the 1.1.0 release (apple#421) Update documentation (apple#420) Make `@OptionGroup(visibility:)` a public API (apple#419) Support an `async` entry point for commands (apple#404) Fix a typo and template links (apple#418) ...
GenerateManualPlugin. The plugin can be invoked from the command line
using
swift package experimental-generate-manual. The plugin isprefixed 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.ToolInfoV0structure from theArgumentParserToolInfolibrary 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.
true language exactly, so it is private to the underlying
generate-manualtool. In the future it would be interesting tofinish fleshing out this MDoc library and spin it out, however this is
not a priority.
this information in manuals.
that might happen to appear in user's help strings.
documentation does not need to be included in the binary itself.
Built with love,
@rauhul