copy by default

Author: Jesse Haigh

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

@@ -124,7 +124,7 @@ public enum RenderBlockContent: Equatable {
         public var code: [String]
         /// Additional metadata for this code block.
         public var metadata: RenderContentMetadata?
-        public var copyToClipboard: Bool = false
+        public var copyToClipboard: Bool = true
 
         /// Make a new `CodeListing` with the given data.
         public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, copyToClipboard: Bool) {
@@ -725,7 +725,7 @@ extension RenderBlockContent: Codable {
                 syntax: container.decodeIfPresent(String.self, forKey: .syntax),
                 code: container.decode([String].self, forKey: .code),
                 metadata: container.decodeIfPresent(RenderContentMetadata.self, forKey: .metadata),
-                copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? false
+                copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? true
             ))
         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)))

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

@@ -49,7 +49,7 @@ struct RenderContentCompiler: MarkupVisitor {
         // Default to the bundle's code listing syntax if one is not explicitly declared in the code block.
         struct ParsedOptions {
             var lang: String?
-            var copy = false
+            var nocopy = false
         }
 
         func parseLanguageString(_ input: String?) -> ParsedOptions {
@@ -63,8 +63,8 @@ struct RenderContentCompiler: MarkupVisitor {
 
             for part in parts {
                 let lower = part.lowercased()
-                if lower == "copy" {
-                    options.copy = true
+                if lower == "nocopy" {
+                    options.nocopy = true
                 } else if options.lang == nil {
                     options.lang = part
                 }
@@ -74,7 +74,7 @@ struct RenderContentCompiler: MarkupVisitor {
 
         let options = parseLanguageString(codeBlock.language)
 
-        return [RenderBlockContent.codeListing(.init(syntax: options.lang ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: options.copy))]
+        return [RenderBlockContent.codeListing(.init(syntax: options.lang ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: !options.nocopy))]
     }
 
     mutating func visitHeading(_ heading: Heading) -> [any RenderContent] {

Sources/SwiftDocC/Semantics/Snippets/Snippet.swift

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

Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

@@ -145,10 +145,17 @@ documentation.
 
 #### Formatting Code Listings
 
-You can add a copy-to-clipboard button to a code listing by including the copy
-option after the name of the programming language for the code listing:
+A copy-to-clipboard button is added to code listings by default behind the
+feature flag `--enable-experimental-code-block`.
+This renders a copy button in the top-right cotner of the code listing in
+generated documentation. When clicked, it copies the contents of the code
+block to the clipboard.
+
+If you don't want a code block to have a copy-to-clipboard button, you can
+include the `nocopy` option after the name of the programming language to
+disable it for that code listing:
 
-```swift, copy
+```swift, nocopy
 struct Sightseeing: Activity {
     func perform(with sloth: inout Sloth) -> Speed {
         sloth.energyLevel -= 10
@@ -157,10 +164,6 @@ struct Sightseeing: Activity {
 }
 ```
 
-This renders a copy button in the top-right cotner of the code listing in
-generated documentation. When clicked, it copies the contents of the code
-block to the clipboard.
-
 DocC uses the programming language you specify to apply the correct syntax 
 color formatting. For the example above, DocC generates the following:
 

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))
+        let code = RenderBlockContent.codeListing(.init(syntax: nil, code: [], metadata: metadata, copyToClipboard: true))
         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)),
+                .codeListing(.init(syntax: "swift", code: ["xcrun xcodebuild -h", "xcrun xcodebuild build -configuration Debug"], metadata: nil, copyToClipboard: true)),
             ]))
         ]
 
@@ -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))], 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))], 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: true))], 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: true))], 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))], 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))], 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: true))], 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: true))], 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/Rendering/RenderContentCompilerTests.swift

@@ -229,7 +229,7 @@ class RenderContentCompilerTests: XCTestCase {
         var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
 
         let source = #"""
-        ```swift, copy
+        ```swift
         let x = 1
         ```
         """#
@@ -245,4 +245,26 @@ class RenderContentCompilerTests: XCTestCase {
 
         XCTAssertEqual(codeListing.copyToClipboard, true)
     }
+
+    func testNoCopyToClipboard() async throws {
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, nocopy
+        let x = 1
+        ```
+        """#
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.copyToClipboard, false)
+    }
 }

Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift

@@ -514,8 +514,8 @@ class ListItemExtractorTests: XCTestCase {
             // ```
             // Inner code block
             // ```
-            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, copyToClipboard: false)),
-        
+            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, copyToClipboard: true)),
+
             // > Warning: Inner aside, with ``ThirdNotFoundSymbol`` link
             .aside(.init(style: .init(asideKind: .warning), content: [
                 .paragraph(.init(inlineContent: [