Did the DocC Snippet support get included in Swift 5.7?

Development Swift-DocC
1

I know I should be able to figure this out, but tracking down the relevant git commits and what's included with the beta release inside Xcode 14 beta1 has me a bit confounded.

Some of the pieces definitely look to be included, but Xcode is kind of cranky about the new directory and failing the builds (with what looks like the symbol _main not getting rewritten - it's reporting Undefined Symbol: _main during linking my snippet1.swift file)

I'm using the main branch of swift-docc-plugin - are there additional command line options I need to activate in order to get it operational to try it in earnest?

2

Hi Joe, are you able to share a repo of a package and the command you are running with the plugin?

I still need to write some end-to-end documentation for this and the implementation is currently being updated per [Accepted with modifications] SE-0356: Swift Snippets. Still working on it, I hope to have the new snippet.hide/snippet.show marks and the explanation comment change from //! to //; the snippetsDirectory override, and the --build-snippets SwiftPM changes for 5.7, with slicing coming later.

You can reach me on the Swift Slack workspace as well.

1 Like
3

It's in an open-source repo, but I'll need to make a branch - I backed it out when it wasn't working so I could continue my refactoring and cleaning work. The failure wasn't in running swift package commands from the CLI - that was working (although I didn't check the output to see how FAR it was working) - it was Xcode 14beta1 failing to compile the code when there was a snippets directory there.

I'll get that branch set up with the replicated scenario to show you what I mean and provide the details here in a short bit. I tried to send you a message on the forums, but your settings are such that I can't send one to you - at least the forums said you weren't accepting direct messages through here.

(I suspect I'm just early to the party, so if there's just an early beta incompatibility with Xcode, that's cool - I'll hold off on trying to use the snippets for a bit)

4

No worries, happy to help. We should be able to get you started even in the current state, so I'm curious to see if something else is going on that I need to fix whenever you have time. Thank you!

1 Like
5

Here's the repo: GitHub - swiftviz/Scale: Scale types usable for visualization, inspired by D3 - the example bits are in the branch snippet-trial (GitHub - swiftviz/Scale at snippet-trial)

The Xcode failure is an error Undefined symbol: main_ (screenshot showing the detail)

Screen Shot 2022-06-21 at 3.39.08 PM
Screen Shot 2022-06-21 at 3.39.08 PM2092×1290 398 KB

Running the documentation build is built into the script docbuild.bash:

 $(xcrun --find swift) package \
     --allow-writing-to-directory ./docs \
     generate-documentation \
     --fallback-bundle-identifier com.github.swiftviz.SwiftVizScale \
     --target SwiftVizScale \
     --output-path ./docs \
     --emit-digest \
     --disable-indexing \
     --transform-for-static-hosting \
     --hosting-base-path 'Scale'

And doesn't generate an error, neither does swift build or swift run snippet1, as you'd hope.

That said, I haven't quite nailed down getting the snippet to show up in the generated docs - my loosey-goosey attempt was knocking together an example article and adding a @Snippet() reference in that. The warning I'm getting there is:
warning: Topic reference 'SwiftVizScale/Snippets/snippet1' couldn't be resolved. No local documentation matches this reference.

Oh - and I just stashed a "preview documentation" script in there as preview.bash with the following command:

 $(xcrun --find swift) package \
     --disable-sandbox \
     --allow-writing-to-directory ./docs \
     preview-documentation \
     --fallback-bundle-identifier com.github.swiftviz.SwiftVizScale \
     --target SwiftVizScale \
     --output-path ./docs \
     --emit-digest \
     --disable-indexing \
     --transform-for-static-hosting \
     --hosting-base-path 'Scale'