Improve snippets

[tib]

• update snippets location, group by year
• fix protobuf & grpc snippets
• fix jwt-kit snippet location
• fixes Fix gRPC snippets #21

[tib]

Seems like CI failed, but swiftinit was able to locate the snippets.

[tayloraswift]

this looks like the same issue @sebsto ran into yesterday

[tib]

Also I've noticed, that the snippets are working on swiftinit, but the path seems to be incorrect, taken this example the path should contain 2025:

@Snippet(path: "site/Snippets/introduction-to-jwts-in-swift", slice: jwt_verify)

The rendered snippet in the article looks just fine: link

This is a strange behavior, what's the correct approach here? @tayloraswift

+1: What's site in the path? 🤔

[tayloraswift]

as described here, the path is not a file path, but a three component string in which the last component is the Snippet module name (not the filename!) and the middle component is the constant string Snippets.

the way Snippets are implemented in SwiftPM, each Snippet is a module, so all Snippets share a global namespace within a build tree. Snippet names also undergo module name mangling, so Snippets whose names differ in special characters only will still collide from SwiftPM’s perspective.

the first component (site) is the package name as specified in the Package.swift manifest.

this has a lot of weird implications, the first being that if the package name contains special characters (like spaces), path is effectively unusable. this is one of the weirder parts about SE-0356.

i recommend using id over path, as the former is a bit clearer about what part of the string is actually meaningful, but keep in mind that id only works on Unidoc.

[tib]

What do you think @Joannis are you fine with migrating to IDs instead of paths?

I'm happy to do the changes, Snippets never really worked with DocC when using Xcode anyway... we always use unidoc to render them, so it makes sense imho.

[Joannis]

I'm completely convinced we should drop Xcode's DocC. Right now we have no way to view updated text quickly through swiftinit's rendering system. So it's a bit of a guessing game requiring many rerenders to get the desired result.

[tayloraswift]

is the unidoc preview tool not working locally?

[tib]

I'll give it a try & update all the path-s to ids to see how it works & looks like.