michael/swift-cli-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat: Working on documentation

Browse Source
This commit is contained in:
Michael Housh
2024-12-06 11:06:10 -05:00
parent 9985b55f88
commit f0873d3b44
16 changed files with 326 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
Sources/CliDoc/Nodes/ExampleSection.swift
View File

@@ -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)
}
}
}

30
Sources/CliDoc/Nodes/Note.swift
View File

@@ -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)

64
Sources/CliDoc/Nodes/ShellCommand.swift
View File

@@ -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()
}
}
}

109
Sources/CliDocCore/Nodes/Section.swift
View File

@@ -1,4 +1,52 @@
// TODO: Add vertical spacing.
/// A section of text nodes, that can contain a header, content, and footer.
///
/// This allows nodes to be grouped and styled together.
///
/// **Example:**
///
/// ```swift
/// let mySection = Section {
/// "My super awesome section content"
/// } header: {
/// "Awesome"
/// } footer: {
/// "Note: this is super awesome".italic()
/// }
/// ```
///
/// **Styling Sections:**
///
/// You can style a section by creating a custom ``SectionStyle``, which gives you the
/// opportunity to arrange and style the nodes within the section.
///
/// ```swift
/// struct MySectionStyle: SectionStyle {
/// func render(content: SectionConfiguration) -> some TextNode {
/// VStack(separator: .newLine(count: 2)) {
/// content.header
/// .color(.green)
/// .bold()
/// .underline()
/// content.content
/// content.footer.italic()
/// }
/// }
/// }
///
/// mySection.style(MySectionStyle())
///
/// print(mySection.render())
/// ```
/// **Note:** colored output / styling only shows in the terminal.
///
/// ```bash
///
/// Awesome
///
/// My super awesome section
///
/// Note: this is super awesome
/// ```
public struct Section<Header: TextNode, Content: TextNode, Footer: TextNode>: TextNode {
@usableFromInline
@@ -10,6 +58,12 @@ public struct Section<Header: TextNode, Content: TextNode, Footer: TextNode>: Te
@usableFromInline
let footer: Footer
/// Create a new section with the given content, header, and footer.
///
/// - Parameters:
/// - content: The content of the section.
/// - header: The header for the section.
/// - footer: The footer for the section.
@inlinable
public init(
@TextBuilder content: () -> Content,
@@ -27,6 +81,11 @@ public struct Section<Header: TextNode, Content: TextNode, Footer: TextNode>: Te
}
public extension Section where Footer == Empty {
/// Create a new section with the given content and header, with no footer.
///
/// - Parameters:
/// - content: The content of the section.
/// - header: The header for the section.
@inlinable
init(
@TextBuilder content: () -> Content,
@@ -37,6 +96,11 @@ public extension Section where Footer == Empty {
}
public extension Section where Header == Empty {
/// Create a new section with the given content and footer, with no header.
///
/// - Parameters:
/// - content: The content of the section.
/// - footer: The footer for the section.
@inlinable
init(
@TextBuilder content: () -> Content,
@@ -46,28 +110,29 @@ public extension Section where Header == Empty {
}
}
public extension Section where Header == Empty, Footer == Empty {
@inlinable
init(
@TextBuilder content: () -> Content
) {
self.init(content: content, header: { Empty() }, footer: { Empty() })
}
}
// MARK: - Style
public extension Section {
/// Style a ``Section`` using the given ``SectionStyle``.
///
/// - Parameters:
/// - style: The section style to use.
@inlinable
func style<S: SectionStyle>(_ style: S) -> some TextNode {
style.render(content: .init(header: header, content: content, footer: footer))
}
}
/// Holds the type-erased values of a ``Section``, used to style a section.
public struct SectionConfiguration {
/// The type-erased header of a section.
public let header: any TextNode
/// The type-erased content of a section.
public let content: any TextNode
/// The type-erased footer of a section.
public let footer: any TextNode
@usableFromInline
@@ -81,13 +146,33 @@ public struct SectionConfiguration {
public protocol SectionStyle: TextModifier where Content == SectionConfiguration {}
public extension SectionStyle where Self == DefaultSectionStyle {
static var `default`: Self { DefaultSectionStyle() }
/// Style a section using the default style, separating the content with
/// a new line between the elements.
static var `default`: Self { `default`(separator: .newLine(count: 2)) }
/// Style a section using the default style, separating the content with
/// given separator between the elements.
///
/// - Parameters:
/// - separator: The separator to use to separate elements in a section.
static func `default`(separator: Separator.Vertical) -> Self {
DefaultSectionStyle(separator: separator)
}
}
/// Represents the default ``SectionStyle``, which arranges the nodes in
/// a ``VStack``, using the separator passed in.
///
/// - SeeAlso: ``SectionStyle/default(separator:)``
///
public struct DefaultSectionStyle: SectionStyle {
@usableFromInline
let separator: Separator.Vertical
public func render(content: SectionConfiguration) -> some TextNode {
VStack(separator: .newLine(count: 2)) {
VStack(separator: separator) {
content.header
content.content
content.footer

3
Sources/CliDocCore/TextStyle.swift
View File

@@ -62,8 +62,7 @@ public extension TextNode {
public protocol TextStyle: TextModifier where Content == TextStyleConfiguration {}
public struct TextStyleConfiguration {
@usableFromInline
let node: any TextNode
public let node: any TextNode
@usableFromInline
init(_ node: any TextNode) {