Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add experimental manual page generation #332

Merged
merged 3 commits into from Jun 6, 2022
Merged

Add experimental manual page generation #332

merged 3 commits into from Jun 6, 2022

Commits on Apr 20, 2022

  1. Add experimental manual page generation

    - 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
    rauhul committed Apr 20, 2022
    Copy the full SHA
    a821a3f View commit details
    Browse the repository at this point in the history

Commits on Apr 26, 2022

  1. Copy the full SHA
    a2b4375 View commit details
    Browse the repository at this point in the history

Commits on Jun 6, 2022

  1. Copy the full SHA
    0f09ac9 View commit details
    Browse the repository at this point in the history