How to run the docc/markdown tests on the Swift book (TSPL)?

Vinicius_Vendramini · January 16, 2025, 3:25pm

Hey yall, I've been exploring the git repo for the Swift Programming Language book and noticed that there are some comments in the markdown files that look like a way to test the code snippets in the book using the Swift compiler. For example:

github.com

swiftlang/swift-book/blob/cc24ca402ef68b58e558ead229e6f4a3ff3c4167/TSPL.docc/GuidedTour/GuidedTour.md?plain=1#L19


      
          <!--
            K&R uses “hello, world”.
            It seems worth breaking with tradition to use proper casing.
          -->
          
          ```swift
          print("Hello, world!")
          // Prints "Hello, world!"
          ```
          
          <!--
            - test: `guided-tour`
          
            ```swifttest
            -> print("Hello, world!")
            <- Hello, world!
            ```
          -->
          
          This syntax should look familiar if you know another language ---
          in Swift, this line of code is a complete program.

However, I didn't find a way to run these tests in the repo. Is that possible? Did I misunderstand the comments, or is it perhaps an internal Apple tool that wasn't included in the repo?

krilnon · January 17, 2025, 3:31am

Yep, those tests are from the older, RST-based pipeline we used to publish the book in the past. There isn’t a way to run them today, but we kept them in the book’s sources with the idea that there might be a way to bring them back later. Here’s the issue for that: Restore tested code listings · Issue #5 · swiftlang/swift-book · GitHub