I've been prototyping work on Swift Snippets, which we previously discussed, and I'm excited to share a proposal pitch with you now.
Here is a link to the proposal text:
The proposal centers around a convention for writing snippets in a Swift package, building and running them, and using them in DocC documentation. There is certainly a lot more we can do with them and this is just a start. Let's hear your thoughts!
To try it out, I have a few branches that you can clone.
This Swift Markdown branch has some example snippets and an article called Snippets. It uses an in-development branch, Swift DocC Plugin:
acgarland/snippets, to build its documentation.
# Build SwiftPM git clone https://github.com/apple/swift-package-manager swiftpm cd swiftpm swift build cd .. # Build Swift DocC git clone https://github.com/apple/swift-docc cd swift-docc swift build cd .. # Get Prebuilt Swift DocC Render git clone firstname.lastname@example.org:apple/swift-docc-render-artifact.git # Build Swift Markdown docs # Substitute your platform for `x86_64-apple-macosx` below as needed. git clone --branch acgarland/snippets email@example.com:bitjammer/swift-markdown.git cd swift-markdown export DOCC_HTML_DIR=/path/to/swift-docc-render-artifact/dist export DOCC_EXEC=/path/to/swift-docc/.build/x86_64-apple-macosx/debug/docc /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-package --disable-sandbox plugin preview-documentation --target Markdown --enable-experimental-snippet-support
From there, open the preview site (
http://localhost:8000/documentation/markdown) and navigate over to the Snippets article, which I've temporarily placed as the first item in the Topics section.