feat: Updates cli documentation to use the swift-cli-doc package.

Sources/hpa/CreateCommand.swift

@@ -8,7 +8,7 @@ struct CreateCommand: AsyncParsableCommand {
 
   static let commandName = "create"
 
-  static let configuration = CommandConfiguration.playbook2(
+  static let configuration = CommandConfiguration.playbook(
     commandName: commandName,
     abstract: "Create a home performance assesment project.",
     examples: (

Sources/hpa/Internal/CommandConfigurationExtensions.swift

@@ -4,66 +4,17 @@ import Rainbow
 
 extension CommandConfiguration {
 
-  static func create(
-    commandName: String,
-    abstract: String,
-    usesExtraArgs: Bool = true,
-    discussion: Discussion
-  ) -> Self {
-    .init(
-      commandName: commandName,
-      abstract: createAbstract(abstract),
-      discussion: discussion.render()
-    )
-  }
-
-  static func create(
-    commandName: String,
-    abstract: String,
-    usesExtraArgs: Bool = true,
-    discussion nodes: [Node]
-  ) -> Self {
-    .init(
-      commandName: commandName,
-      abstract: createAbstract(abstract),
-      discussion: Discussion(nodes: nodes, usesExtraArgs: usesExtraArgs).render()
-    )
-  }
-
-  static func playbook2(
-    commandName: String,
-    abstract: String,
-    parentCommand: String? = nil,
-    examples: (label: String, example: String)...
-  ) -> Self {
-    .init(
-      commandName: commandName,
-      abstract: Abstract { abstract.blue },
-      usage: """
-      \(Constants.appName)\(parentCommand != nil ? " \(parentCommand!)" : "") \(commandName)
-      """.blue.bold.italic
-        + " [OPTIONS]".green
-        + " [ARGUMENTS]".cyan
-        + " --" + " [EXTRA-OPTIONS...]".magenta,
-      discussion: CliDoc.Discussion.playbook(examples: examples)
-    )
-  }
-
   static func playbook(
     commandName: String,
     abstract: String,
     parentCommand: String? = nil,
-    examples: (label: String, example: String)...
+    examples: Example...
   ) -> Self {
-    .create(
+    .init(
       commandName: commandName,
-      abstract: abstract,
-      discussion: .default(
-        usesExtraArgs: true,
-        parentCommand: parentCommand,
-        examples: examples,
-        seeAlso: .seeAlso(label: "Ansible playbook options.", command: "ansible-playbook")
-      )
+      abstract: Abstract { abstract.blue },
+      usage: Usage.default(commandName: commandName, parentCommand: parentCommand),
+      discussion: Discussion.playbook(examples: examples)
     )
   }
 }
@@ -72,272 +23,27 @@ func createAbstract(_ string: String) -> String {
   "\(string.blue)"
 }
 
-// TODO: Remove
-struct Discussion {
-  let nodes: [Node]
+extension Usage where Content == AnyTextNode {
 
-  static func `default`(
-    usesExtraArgs: Bool,
-    parentCommand: String?,
-    examples: [(label: String, example: String)],
-    seeAlso: Node?
-  ) -> Self {
-    var nodes = Array.defaultNodes + examples.nodes(parentCommand)
-    if let seeAlso { nodes.append(seeAlso) }
-    if usesExtraArgs && examples.count > 0 { nodes.append(.important(label: Constants.importantExtraArgsNote)) }
-    return .init(
-      nodes: nodes,
-      usesExtraArgs: usesExtraArgs
-    )
-  }
-
-  init(usesExtraArgs: Bool = true, _ nodes: Node...) {
-    self.init(nodes: nodes, usesExtraArgs: usesExtraArgs)
-  }
-
-  init(nodes: [Node], usesExtraArgs: Bool = true) {
-    var nodes = nodes
-
-    if let firstExampleIndex = nodes.firstIndex(where: \.isExampleNode) {
-      nodes.insert(.exampleHeading, at: firstExampleIndex)
-    }
-
-    if usesExtraArgs {
-      if let lastExampleIndex = nodes.lastIndex(where: \.isExampleNode) {
-        guard case let .example(.container(exampleNodes, _)) = nodes[lastExampleIndex] else {
-          // this should never happen.
-          print(nodes[lastExampleIndex])
-          fatalError()
+  static func `default`(commandName: String, parentCommand: String?) -> Self {
+    .init {
+      HStack {
+        HStack {
+          "\(Constants.appName)"
+          if let parentCommand {
+            parentCommand
+          }
+          commandName
         }
+        .color(.blue).bold()
 
-        // Get the last element of the example container, which will be the
-        // text for the example.
-        guard let exampleNode = exampleNodes.last else {
-          print(exampleNodes)
-          fatalError()
-        }
-
-        // replace the first element, which is the header so that we can
-        // replace it with a new header.
-        nodes.insert(
-          .example(.exampleContainer(
-            "Passing extra args.",
-            "\(exampleNode.render().replacingOccurrences(of: "  $ ", with: ""))"
-              + " -- --vault-id \"myId@$SCRIPTS/vault-gopass-client\""
-          )),
-          at: nodes.index(after: lastExampleIndex)
-        )
+        "[OPTIONS]".color(.green)
+        "[ARGUMENTS]".color(.cyan)
+        "--"
+        "[EXTRA-OPTIONS]".color(.magenta)
       }
-    }
-    self.nodes = nodes
-  }
 
-  func render() -> String { nodes.render() }
-}
-
-enum Node {
-
-  struct Separator {
-
-    let string: String
-    let count: Int
-
-    init(_ string: String, repeating count: Int = 1) {
-      self.string = string
-      self.count = count
-    }
-
-    var value: String { string.repeating(count) }
-
-    static var empty: Self { .init("") }
-
-    static func space(_ count: Int = 1) -> Self {
-      .init(" ", repeating: count)
-    }
-
-    static func newLine(_ count: Int = 1) -> Self {
-      .init("\n", repeating: count)
-    }
-
-    static func tab(_ count: Int) -> Self {
-      .init("\t", repeating: count)
-    }
-  }
-
-  /// A container that holds onto other nodes to be rendered.
-  indirect case container(_ nodes: [Node], separator: Separator = .newLine())
-
-  /// A container to identify example nodes, so some other nodes can get injected
-  /// when this is rendered.
-  ///
-  /// NOTE: Things blow up if this is not used correctly, at least when using the `Discussion`
-  ///       to render the nodes, so this is not safe to create aside from the static methods that
-  ///       create an example node. If not using in the context of a `Discussion` then it's fine to
-  ///       use, as it doesn't do anything except stand as an type identifier.
-  indirect case example(_ node: Node)
-
-  /// A root node that renders the given string without modification.
-  case text(_ text: String)
-
-  static func container(separator: Separator = .newLine(), _ nodes: Node...) -> Self {
-    .container(nodes, separator: separator)
-  }
-
-  static func container(_ lhs: Node, _ rhs: Node, separator: Separator = .newLine()) -> Self {
-    .container([lhs, rhs], separator: separator)
-  }
-
-  static func styledText(_ text: String, color: NamedColor? = nil, styles: [Style]? = nil) -> Self {
-    var string = text
-    if let color {
-      string = string.applyingColor(color)
-    }
-    if let styles {
-      for style in styles {
-        string = string.applyingStyle(style)
-      }
-    }
-    return .text(string)
-  }
-
-  static func styledText(_ text: String, color: NamedColor? = nil, style: Style) -> Self {
-    .styledText(text, color: color, styles: [style])
-  }
-
-  static func boldYellowText(_ text: String) -> Self {
-    .styledText(text, color: .yellow, styles: [.bold])
-  }
-
-  static func section(header: Node, content: Node, separator: Separator = .newLine()) -> Self {
-    .container([header, content], separator: separator)
-  }
-
-  static func section(header: String, label: Node, separator: Separator = .newLine()) -> Self {
-    .section(header: .boldYellowText(header), content: label, separator: separator)
-  }
-
-  static func important(label: String) -> Self {
-    .section(
-      header: .text("IMPORTANT NOTE:".red.bold.underline),
-      content: .text(label.italic),
-      separator: .newLine()
-    )
-  }
-
-  static func note(_ text: String, inline: Bool = true) -> Self {
-    .section(header: "NOTE:", label: .text(text.italic), separator: inline ? .space() : .newLine())
-  }
-
-  static func shellCommand(_ text: String, symbol: String = " $") -> Self {
-    .text("\(symbol) \(text)")
-  }
-
-  static func seeAlso(label: String, command: String, appendHelpToCommand: Bool = true) -> Self {
-    .container([
-      .container(.boldYellowText("See Also:"), .text(label.italic), separator: .space()),
-      .shellCommand("\(appendHelpToCommand ? command + " --help" : command)")
-    ])
-  }
-
-  static var exampleHeading: Self {
-    .section(header: "Examples:", label: .text("Some common examples."), separator: .space())
-  }
-
-  var isExampleNode: Bool {
-    if case .example = self { return true }
-    return false
-  }
-
-  fileprivate static func exampleContainer(_ label: String, _ command: String) -> Self {
-    .container(
-      .exampleLabel("\(label)\n"),
-      .shellCommand(command, symbol: "  $"),
-      separator: .empty
-    )
-  }
-
-  /// Renders an example usage of the command.
-  static func example(label: String, example: String, parentCommand: String?) -> Self {
-    let string: String
-    if let parent = parentCommand {
-      string = "\(Constants.appName) \(parent) \(example)"
-    } else {
-      string = "\(Constants.appName) \(example)"
-    }
-    return .example(.exampleContainer(label, string))
-  }
-
-  static func exampleLabel(_ label: String) -> Node {
-    .text("  \(label.green.italic)")
-  }
-
-  func render() -> String {
-    switch self {
-    case let .container(nodes, separator):
-      return nodes.render(separator: separator)
-    case let .text(text):
-      return text
-    case let .example(node):
-      return node.render()
+      .eraseToAnyTextNode()
     }
   }
 }
-
-extension Node: ExpressibleByStringLiteral {
-
-  typealias StringLiteralType = String
-
-  init(stringLiteral value: String) {
-    self = .text(value)
-  }
-}
-
-extension Node: ExpressibleByArrayLiteral {
-
-  typealias ArrayLiteralElement = Node
-
-  init(arrayLiteral elements: Node...) {
-    self = .container(elements)
-  }
-}
-
-private extension Array where Element == (label: String, example: String) {
-  func nodes(_ parentCommand: String?) -> [Node] {
-    map { .example(label: $0.label, example: $0.example, parentCommand: parentCommand) }
-  }
-}
-
-extension Array where Element == Node {
-
-  static var defaultNodes: Self {
-    [.note("Most options are not required if you have a configuration file setup.")]
-  }
-
-  fileprivate func render(separator: Node.Separator = .newLine()) -> String {
-    map {
-      // Strip of any new-line characters from the last section of the rendered string
-      // of the node.  This allows us to have a consistent single new-line between each
-      // rendered node.
-      var string = $0.render()[...]
-      while string.hasSuffix("\n") {
-        string = string.dropLast()
-      }
-      return String(string)
-    }
-    .joined(separator: separator.value)
-  }
-}
-
-private extension String {
-  func repeating(_ count: Int) -> Self {
-    guard count > 0 else { return self }
-    var count = count
-    var output = self
-
-    while count > 0 {
-      output = "\(output)\(self)"
-      count -= 1
-    }
-    return output
-  }
-}

Sources/hpa/Internal/Discussion+playbook.swift

@@ -1,86 +1,127 @@
 import CliDoc
 
-extension CliDoc.Discussion {
+extension CliDoc.Discussion where Content == AnyTextNode {
   static func playbook(
-    examples: [(label: String, example: String)]
+    examples: [Example]
   ) -> Self {
     .init {
-      Section {
+      VStack {
         Note.mostOptionsNotRequired
-        Examples(examples: examples)
+        ExampleSection.default(examples: examples)
         SeeAlso(label: "Ansible playbook options.", command: "ansible-playbook --help")
         ImportantNote.passingExtraArgs
       }
-      // .labeledContentStyle(.custom("foo:"))
+      .separator(.newLine(count: 2))
+      .eraseToAnyTextNode()
     }
   }
 }
 
-extension ShellCommand {
+extension Array where Element == Example {
+  func addingPassingOptions(command: String) -> Self {
+    var output = self
+    output.append((
+      label: "Passing extra arguments / options",
+      example: "\(command) -- --vaultId=myId@$SCRIPTS/vault-gopass-client"
+    ))
+    return output
+  }
+}
+
+extension ExampleSection where Header == String, Label == String {
+  static func `default`(examples: [Example], usesPassingExtraOptions: Bool = true) -> some TextNode {
+    var examples = examples
+    if usesPassingExtraOptions, let first = examples.first {
+      examples = examples.addingPassingOptions(command: first.example)
+    }
+    return Self(examples: examples) {
+      "EXAMPLES:"
+    } label: {
+      "Some common usage examples."
+    }
+    .exampleStyle(HPAExampleStyle())
+  }
+}
+
+struct HPAExampleStyle: ExampleStyle {
+
+  func render(content: ExampleConfiguration) -> some TextNode {
+    VStack {
+      content.examples.map { example in
+        VStack {
+          example.label.color(.green).bold()
+          ShellCommand.hpaCommand(example.example)
+        }
+      }
+    }
+    .separator(.newLine(count: 2))
+  }
+}
+
+extension ShellCommand where Content == String, Symbol == String {
   static func hpaCommand(_ command: String) -> Self {
-    .init(command: "\(Constants.appName) \(command)")
+    .init { "\(Constants.appName) \(command)" } symbol: { "$" }
   }
 }
 
-struct SeeAlso: NodeRepresentable {
+struct SeeAlso<Label: TextNode, Content: TextNode>: TextNode {
 
-  let node: any NodeRepresentable
-
-  init(label: String, command: String) {
-    self.node = Group(separator: "\n") {
-      Note("SEE ALSO:") {
-        label
-      }
-      ShellCommand(command: command)
-    }
-  }
-
-  func render() -> String {
-    node.render()
-  }
-
-}
-
-struct Examples: NodeRepresentable {
-  typealias Example = (label: String, example: String)
-  let examples: [Example]
-
-  func render() -> String {
-    Group(separator: "\n") {
-      Note("EXAMPLES:") { "Common usage examples." }
-      for (label, command) in examples {
-        LabeledContent("\t\(label.green.bold)", separator: "\n") {
-          ShellCommand.hpaCommand(command)
-        }
-      }
-      if let first = examples.first {
-        LabeledContent("\n\tPassing extra options.".green.bold, separator: "\n") {
-          ShellCommand.hpaCommand("\(first.example) -- --vault-id \"myId@$SCRIPTS/vault-gopass-client\"")
-        }
-      }
-    }.render()
-  }
-}
-
-struct Note: NodeRepresentable {
-
-  let node: any NodeRepresentable
+  let title = "SEE ALSO:"
+  let label: Label
+  let content: Content
 
   init(
-    _ label: String = "NOTE:",
-    @NodeBuilder _ content: () -> any NodeRepresentable
+    @TextBuilder content: () -> Content,
+    @TextBuilder label: () -> Label
   ) {
-    self.node = LabeledContent(
-      separator: " ",
-      label: { label.yellow.bold },
-      content: { content().style(.italic) }
-    )
+    self.content = content()
+    self.label = label()
   }
 
-  func render() -> String {
-    node.render()
+  var body: some TextNode {
+    VStack {
+      LabeledContent {
+        label.italic()
+      } label: {
+        title.color(.yellow).bold().underline()
+      }
+      ShellCommand { content } symbol: { "$" }
+    }
+  }
+}
+
+extension SeeAlso where Content == String, Label == Empty {
+  init(command: String) {
+    self.init { "\(Constants.appName) \(command)" } label: { Empty() }
+  }
+}
+
+extension SeeAlso where Content == String, Label == String {
+  init(label: String, command: String) {
+    self.init { "\(Constants.appName) \(command)" } label: { label }
+  }
+}
+
+struct Note<Content: TextNode>: TextNode {
+
+  let label: String = "NOTE:"
+  let content: Content
+
+  init(
+    @TextBuilder _ content: () -> Content
+  ) {
+    self.content = content()
   }
 
+  var body: some TextNode {
+    HStack {
+      label.color(.yellow).bold()
+      content
+    }
+  }
+}
+
+extension Note where Content == String {
   static var mostOptionsNotRequired: Self {
     .init {
       "Most options are not required if you have a configuration file setup."
@@ -88,26 +129,27 @@ struct Note: NodeRepresentable {
   }
 }
 
-// TODO: Fix the text.
-struct ImportantNote: NodeRepresentable {
+struct ImportantNote<Content: TextNode>: TextNode {
 
-  let node: any NodeRepresentable
+  let label: String = "IMPORTANT NOTE:"
+  let content: Content
 
   init(
-    _ label: String = "IMPORTANT NOTE:",
-    @NodeBuilder _ content: () -> any NodeRepresentable
+    @TextBuilder _ content: () -> Content
   ) {
-    self.node = LabeledContent(
-      separator: "\n",
-      label: { label.red.bold.underline },
-      content: { content().style(.italic) }
-    )
+    self.content = content()
   }
 
-  func render() -> String {
-    node.render()
+  var body: some TextNode {
+    HStack {
+      label.color(.red).bold().underline()
+      content
+    }
   }
 
+}
+
+extension ImportantNote where Content == String {
   static var passingExtraArgs: Self {
     .init {
       """

Sources/hpa/VaultCommands/VaultCommand.swift

@@ -1,4 +1,5 @@
 import ArgumentParser
+import CliDoc
 
 struct VaultCommand: AsyncParsableCommand {
 
@@ -7,12 +8,21 @@ struct VaultCommand: AsyncParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: commandName,
     abstract: createAbstract("Vault commands."),
-    discussion: Discussion(
-      .text("""
-      Allows you to run `ansible-vault` commands on your project or project-template.
-      """),
-      .seeAlso(label: "Ansible Vault", command: "ansible-vault")
-    ).render(),
+    discussion: Discussion {
+      VStack {
+        """
+        Allows you to run `ansible-vault` commands on your project or project-template.
+
+        Ansible-vault allows you to store sensitive variables in an encrypted format.
+        """
+        SeeAlso {
+          "ansible-vault --help"
+        } label: {
+          "Ansible Vault"
+        }
+      }
+      .separator(.newLine(count: 2))
+    },
     subcommands: [
       EncryptCommand.self, DecryptCommand.self
     ]