feat: Working on documentation

Sources/CliDoc/Nodes/ExampleSection.swift

@@ -1,7 +1,8 @@
 import Rainbow
 
+public typealias Example = (label: String, example: String)
+
 public struct ExampleSection<Header: TextNode, Label: TextNode>: TextNode {
-  public typealias Example = (label: String, example: String)
 
   @usableFromInline
   let configuration: ExampleSectionConfiguration
@@ -40,29 +41,26 @@ public struct ExampleSection<Header: TextNode, Label: TextNode>: TextNode {
 
 /// The type-erased configuration of an ``ExampleSection``
 public struct ExampleSectionConfiguration {
-  @usableFromInline
-  let title: any TextNode
+  public let title: any TextNode
+
+  public let label: any TextNode
+
+  public let examples: [Example]
 
   @usableFromInline
-  let label: any TextNode
-
-  @usableFromInline
-  let examples: [ExampleSection.Example]
-
-  @usableFromInline
-  init(title: any TextNode, label: any TextNode, examples: [ExampleSection.Example]) {
+  init(title: any TextNode, label: any TextNode, examples: [Example]) {
     self.title = title
     self.label = label
     self.examples = examples
   }
 }
 
+/// The configuration context for the `examples` of an ``ExampleSection``.
 public struct ExampleConfiguration {
-  @usableFromInline
-  let examples: [ExampleSection.Example]
+  public let examples: [Example]
 
   @usableFromInline
-  init(examples: [ExampleSection.Example]) {
+  init(examples: [Example]) {
     self.examples = examples
   }
 }
@@ -85,7 +83,7 @@ public extension ExampleSection {
   }
 }
 
-extension Array where Element == ExampleSection.Example {
+extension Array where Element == Example {
   @inlinable
   func exampleStyle<S: ExampleStyle>(_ style: S) -> some TextNode {
     style.render(content: .init(examples: self))
@@ -152,8 +150,8 @@ public struct DefaultExampleStyle: ExampleStyle {
     VStack(separator: .newLine(count: 2)) {
       content.examples.map { example in
         VStack {
-          Label(example.label.green.bold)
-          ShellCommand { example.example }.style(.default)
+          example.label.color(.green).bold()
+          ShellCommand(example.example).style(.default)
         }
       }
     }

Sources/CliDoc/Nodes/Note.swift

@@ -1,3 +1,4 @@
+import CliDocCore
 import Rainbow
 
 public struct Note<Label: TextNode, Content: TextNode>: TextNode {
@@ -18,7 +19,7 @@ public struct Note<Label: TextNode, Content: TextNode>: TextNode {
 
   @inlinable
   public var body: some TextNode {
-    noteStyle(.default)
+    style(.default)
   }
 }
 
@@ -26,11 +27,10 @@ public extension Note where Label == String {
 
   @inlinable
   init(
-    _ label: String = "NOTE:",
+    _ label: @autoclosure () -> String = "NOTE:",
     @TextBuilder content: () -> Content
   ) {
-    self.label = label
-    self.content = content()
+    self.init(label, content: content)
   }
 
   static func important(
@@ -48,6 +48,7 @@ public extension Note where Label == String {
   }
 }
 
+// TODO: Remove the important and see also.
 public extension Note where Label == String, Content == String {
 
   @inlinable
@@ -74,28 +75,39 @@ public extension Note where Label == String, Content == String {
 }
 
 public struct NoteStyleConfiguration {
+  @usableFromInline
   let label: any TextNode
+
+  @usableFromInline
   let content: any TextNode
+
+  @usableFromInline
+  init(label: any TextNode, content: any TextNode) {
+    self.label = label
+    self.content = content
+  }
 }
 
 public extension Note {
-  func noteStyle<S: NoteStyleModifier>(_ modifier: S) -> some TextNode {
-    modifier.render(content: .init(label: label, content: content))
+  @inlinable
+  func style<S: NoteStyle>(_ modifier: S) -> some TextNode {
+    modifier.render(content: NoteStyleConfiguration(label: label, content: content))
   }
 }
 
 // MARK: - Style
 
-public protocol NoteStyleModifier: TextModifier where Content == NoteStyleConfiguration {}
+public protocol NoteStyle: TextModifier where Content == NoteStyleConfiguration {}
 
-public extension NoteStyleModifier where Self == DefaultNoteStyle {
+public extension NoteStyle where Self == DefaultNoteStyle {
   static var `default`: Self {
     DefaultNoteStyle()
   }
 }
 
-public struct DefaultNoteStyle: NoteStyleModifier {
+public struct DefaultNoteStyle: NoteStyle {
 
+  @inlinable
   public func render(content: NoteStyleConfiguration) -> some TextNode {
     HStack {
       content.label.color(.yellow).textStyle(.bold)

Sources/CliDoc/Nodes/ShellCommand.swift

@@ -1,20 +1,43 @@
+import CliDocCore
 import Rainbow
 
-public struct ShellCommand<Content: TextNode>: TextNode {
+/// Represents a shell command text node, with a symbol and the content of
+/// the command.  Used for displaying example shell commands.
+///
+///
+public struct ShellCommand<Content: TextNode, Symbol: TextNode>: TextNode {
 
   @usableFromInline
-  var symbol: any TextNode
+  let symbol: Symbol
 
   @usableFromInline
-  var content: Content
+  let content: Content
 
+  /// Create a new shell command with the given content and symbol.
+  ///
+  /// - Parameters:
+  ///   - content: The shell command to display.
+  ///   - symbol: The symbol to use in front of the shell command.
   @inlinable
   public init(
-    symbol: any TextNode = "$",
+    @TextBuilder content: () -> Content,
+    @TextBuilder symbol: () -> Symbol
+  ) {
+    self.symbol = symbol()
+    self.content = content()
+  }
+
+  /// Create a new shell command with the given content and symbol.
+  ///
+  /// - Parameters:
+  ///   - symbol: The symbol to use in front of the shell command.
+  ///   - content: The shell command to display.
+  @inlinable
+  public init(
+    symbol: @autoclosure () -> Symbol,
     @TextBuilder content: () -> Content
   ) {
-    self.symbol = symbol
-    self.content = content()
+    self.init(content: content, symbol: symbol)
   }
 
   @inlinable
@@ -23,22 +46,35 @@ public struct ShellCommand<Content: TextNode>: TextNode {
   }
 }
 
-public extension ShellCommand where Content == String {
+public extension ShellCommand where Content == String, Symbol == String {
+  /// Create a new shell command with the given content and symbol.
+  ///
+  /// - Parameters:
+  ///   - content: The shell command to display.
+  ///   - symbol: The symbol to use in front of the shell command.
   @inlinable
   init(
-    _ content: String,
-    symbol: any TextNode = "$"
+    _ content: @autoclosure () -> String,
+    symbol: @autoclosure () -> String = "$"
   ) {
-    self.init(symbol: symbol) { content }
+    self.init(content: content, symbol: symbol)
   }
 }
 
 public struct ShellCommandConfiguration {
-  let symbol: any TextNode
-  let content: any TextNode
+  public let symbol: any TextNode
+
+  public let content: any TextNode
+
+  @usableFromInline
+  init(symbol: any TextNode, content: any TextNode) {
+    self.symbol = symbol
+    self.content = content
+  }
 }
 
 public extension ShellCommand {
+  @inlinable
   func style<S: ShellCommandStyle>(_ style: S) -> some TextNode {
     style.render(content: .init(symbol: symbol, content: content))
   }
@@ -46,7 +82,7 @@ public extension ShellCommand {
 
 // MARK: - Style
 
-public protocol ShellCommandStyle: TextModifier where Self.Content == ShellCommandConfiguration {}
+public protocol ShellCommandStyle: TextModifier where Content == ShellCommandConfiguration {}
 
 public extension ShellCommandStyle where Self == DefaultShellCommandStyle {
   static var `default`: Self { DefaultShellCommandStyle() }
@@ -57,7 +93,7 @@ public struct DefaultShellCommandStyle: ShellCommandStyle {
   public func render(content: ShellCommandConfiguration) -> some TextNode {
     HStack {
       content.symbol
-      content.content.textStyle(.italic)
+      content.content.italic()
     }
   }
 }