showLineNumbers option

Author: Jesse Haigh

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -127,12 +127,14 @@ public enum RenderBlockContent: Equatable {
         public var copyToClipboard: Bool = true
         public var wrap: Int = 100
         public var highlight: [Int] = [Int]()
+        public var showLineNumbers: Bool = false
         public var strikeout: [Int] = [Int]()
 
         public enum OptionName: String, CaseIterable {
             case nocopy
             case wrap
             case highlight
+            case showLineNumbers
             case strikeout
             case unknown
 
@@ -146,13 +148,14 @@ public enum RenderBlockContent: Equatable {
         }
 
         /// Make a new `CodeListing` with the given data.
-        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, copyToClipboard: Bool, wrap: Int, highlight: [Int], strikeout: [Int]) {
+        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, copyToClipboard: Bool, wrap: Int, highlight: [Int], strikeout: [Int], showLineNumbers: Bool) {
             self.syntax = syntax
             self.code = code
             self.metadata = metadata
             self.copyToClipboard = copyToClipboard
             self.wrap = wrap
             self.highlight = highlight
+            self.showLineNumbers = showLineNumbers
             self.strikeout = strikeout
         }
     }
@@ -721,7 +724,7 @@ extension RenderBlockContent.Table: Codable {
 extension RenderBlockContent: Codable {
     private enum CodingKeys: CodingKey {
         case type
-        case inlineContent, content, caption, style, name, syntax, code, level, text, items, media, runtimePreview, anchor, summary, example, metadata, start, copyToClipboard, wrap, highlight, strikeout
+        case inlineContent, content, caption, style, name, syntax, code, level, text, items, media, runtimePreview, anchor, summary, example, metadata, start, copyToClipboard, wrap, highlight, strikeout, showLineNumbers
         case request, response
         case header, rows
         case numberOfColumns, columns
@@ -751,7 +754,8 @@ extension RenderBlockContent: Codable {
                 copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy,
                 wrap: container.decodeIfPresent(Int.self, forKey: .wrap) ?? 0,
                 highlight: container.decodeIfPresent([Int].self, forKey: .highlight) ?? [Int](),
-                strikeout: container.decodeIfPresent([Int].self, forKey: .strikeout) ?? [Int]()
+                strikeout: container.decodeIfPresent([Int].self, forKey: .strikeout) ?? [Int](),
+                showLineNumbers: container.decodeIfPresent(Bool.self, forKey: .showLineNumbers) ?? false
             ))
         case .heading:
             self = try .heading(.init(level: container.decode(Int.self, forKey: .level), text: container.decode(String.self, forKey: .text), anchor: container.decodeIfPresent(String.self, forKey: .anchor)))
@@ -859,6 +863,7 @@ extension RenderBlockContent: Codable {
             try container.encode(l.wrap, forKey: .wrap)
             try container.encode(l.highlight, forKey: .highlight)
             try container.encode(l.strikeout, forKey: .strikeout)
+            try container.encode(l.showLineNumbers, forKey: .showLineNumbers)
         case .heading(let h):
             try container.encode(h.level, forKey: .level)
             try container.encode(h.text, forKey: .text)

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

@@ -58,7 +58,8 @@ struct RenderContentCompiler: MarkupVisitor {
                 copyToClipboard: true, // default value
                 wrap: 0, // default value
                 highlight: [Int](), // default value
-                strikeout: [Int]() // default value
+                strikeout: [Int](), // default value
+                showLineNumbers: false, // default value
             )
 
             // apply code block options
@@ -76,6 +77,8 @@ struct RenderContentCompiler: MarkupVisitor {
                     listing.highlight = parseCodeBlockOptionArray(value) ?? []
                 case .strikeout:
                     listing.strikeout = parseCodeBlockOptionArray(value) ?? []
+                case .showLineNumbers:
+                    listing.showLineNumbers = true
                 case .unknown:
                     break
                 }
@@ -84,7 +87,7 @@ struct RenderContentCompiler: MarkupVisitor {
             return [RenderBlockContent.codeListing(listing)]
 
         } else {
-            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: false, wrap: 0, highlight: [Int](), strikeout: [Int]()))]
+            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: false, wrap: 0, highlight: [Int](), strikeout: [Int](), showLineNumbers: false))]
         }
     }
 

Sources/SwiftDocC/Semantics/Snippets/Snippet.swift

@@ -84,12 +84,12 @@ extension Snippet: RenderableDirectiveConvertible {
                 let minimumIndentation = lines.map { $0.prefix { $0.isWhitespace }.count }.min() ?? 0
                 let trimmedLines = lines.map { String($0.dropFirst(minimumIndentation)) }
                 let copy = FeatureFlags.current.isExperimentalCodeBlockEnabled
-                return [RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: trimmedLines, metadata: nil, copyToClipboard: copy, wrap: 0, highlight: [Int](), strikeout: [Int]()))]
+                return [RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: trimmedLines, metadata: nil, copyToClipboard: copy, wrap: 0, highlight: [Int](), strikeout: [Int](), showLineNumbers: false))]
             } else {
                 // Render the whole snippet with its explanation content.
                 let docCommentContent = snippetEntity.markup.children.flatMap { contentCompiler.visit($0) }
                 let copy = FeatureFlags.current.isExperimentalCodeBlockEnabled
-                let code = RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: snippetMixin.lines, metadata: nil, copyToClipboard: copy, wrap: 0, highlight: [Int](), strikeout: [Int]()))
+                let code = RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: snippetMixin.lines, metadata: nil, copyToClipboard: copy, wrap: 0, highlight: [Int](), strikeout: [Int](), showLineNumbers: false))
                 return docCommentContent + [code]
             }
     }

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json

@@ -809,6 +809,9 @@
                     "copyToClipboard": {
                         "type": "boolean"
                     },
+                    "showLineNumbers": {
+                        "type": "boolean"
+                    },
                     "wrap": {
                         "type": "integer"
                     },

Sources/SwiftDocC/Utility/ParseLanguageString.swift

@@ -44,6 +44,8 @@ public func tokenizeLanguageString(_ input: String?) -> (lang: String?, tokens:
             let key = part.trimmingCharacters(in: .whitespaces).lowercased()
             if key == "nocopy" {
                 tokens.append((.nocopy, nil as String?))
+            } else if key == "showlinenumbers" {
+                tokens.append((.showLineNumbers, nil as String?))
             } else if key == "wrap" {
                 tokens.append((.wrap, nil as String?))
             } else if key == "highlight" {

Tests/SwiftDocCTests/Checker/Checkers/InvalidCodeBlockOptionTests.swift

@@ -24,7 +24,7 @@ let a = 1
         var checker = InvalidCodeBlockOption(sourceFile: nil)
         checker.visit(document)
         XCTAssertTrue(checker.problems.isEmpty)
-        XCTAssertEqual(RenderBlockContent.CodeListing.knownOptions, ["highlight", "nocopy", "strikeout", "unknown", "wrap"])
+        XCTAssertEqual(RenderBlockContent.CodeListing.knownOptions, ["highlight", "nocopy", "strikeout", "unknown", "wrap", "showLineNumbers"])
     }
 
     func testOption() {

Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift

@@ -54,7 +54,7 @@ class RenderContentMetadataTests: XCTestCase {
             RenderInlineContent.text("Content"),
         ])
 
-        let code = RenderBlockContent.codeListing(.init(syntax: nil, code: [], metadata: metadata, copyToClipboard: false, wrap: 0, highlight: [], strikeout: []))
+        let code = RenderBlockContent.codeListing(.init(syntax: nil, code: [], metadata: metadata, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [], showLineNumbers: false))
         let data = try JSONEncoder().encode(code)
         let roundtrip = try JSONDecoder().decode(RenderBlockContent.self, from: data)
 

Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift

@@ -44,7 +44,7 @@ class RenderNodeSerializationTests: XCTestCase {
                     .strong(inlineContent: [.text("Project > Run")]),
                     .text(" menu item, or the following code:"),
                 ])),
-                .codeListing(.init(syntax: "swift", code: ["xcrun xcodebuild -h", "xcrun xcodebuild build -configuration Debug"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [])),
+                .codeListing(.init(syntax: "swift", code: ["xcrun xcodebuild -h", "xcrun xcodebuild build -configuration Debug"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [], showLineNumbers: false)),
             ]))
         ]
 
@@ -71,16 +71,16 @@ class RenderNodeSerializationTests: XCTestCase {
         let assessment1 = TutorialAssessmentsRenderSection.Assessment(title: [.paragraph(.init(inlineContent: [.text("Lorem ipsum dolor sit amet?")]))],
                                                                      content: nil,
                                                                      choices: [
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["override func viewDidLoad() {", "super.viewDidLoad()", "}"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: []))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "That's right!"),
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: []))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Not quite."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["override func viewDidLoad() {", "super.viewDidLoad()", "}"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [], showLineNumbers: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "That's right!"),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [], showLineNumbers: false))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Not quite."),
             .init(content: [.paragraph(.init(inlineContent: [.text("None of the above.")]))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: nil),
         ])
 
         let assessment2 = TutorialAssessmentsRenderSection.Assessment(title: [.paragraph(.init(inlineContent: [.text("Duis aute irure dolor in reprehenderit?")]))],
                                                                      content: [.paragraph(.init(inlineContent: [.text("What is the airspeed velocity of an unladen swallow?")]))],
                                                                      choices: [
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["super.viewWillAppear()"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: []))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Correct."),
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: []))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Yep."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["super.viewWillAppear()"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [], showLineNumbers: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Correct."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [], showLineNumbers: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Yep."),
             .init(content: [.paragraph(.init(inlineContent: [.text("None of the above.")]))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Close!"),
         ])
 

Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift

@@ -514,7 +514,7 @@ class ListItemExtractorTests: XCTestCase {
             // ```
             // Inner code block
             // ```
-            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [])),
+            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, copyToClipboard: false, wrap: 0, highlight: [], strikeout: [], showLineNumbers: false)),
 
             // > Warning: Inner aside, with ``ThirdNotFoundSymbol`` link
             .aside(.init(style: .init(asideKind: .warning), content: [