Hi everyone,
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!
Trying it out
To try it out, I have a few branches that you can clone.
Swift Markdown: acgarland/snippets
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.
You'll need to use a fresh toolchain, or clone the main
branch of SwiftPM and DocC. Here's a run-through of what you can do at the command line to try it out:
# 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 git@github.com: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 git@github.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.