Snippets should not be limited to Snippets directory

[ktoso]

Feature Name

Snippets from any directory

Description

The docs say:

If you prefer, you can specify the relative path from the package’s root directory (by including a
“Snippets/” prefix). You can also include the package name—as defined in Package.swift—before the
“Snippets/” prefix. Neither of these leading path components are necessary because all your snippet code
files are always located in your package’s “Snippets” directory.

Earlier Versions
Before Swift-DocC 6.2.1, the @Snippet path needed to include both the package name component and the “Snippets” component: @Snippet(path: "my-package/Snippets/example-snippet")

Which basically means I have to copy or symlink my Samples/ projects into Snippets in order to use snippets, very confusing people contributing to the project.

We should be able to just

`@Snippet(path: "my-package/Samples/MySample/Sources/FirstExample/example-snippet")`

because this way those are not only compiled but also run tests against as I verify my samples.

Motivation

swift-java has extensive examples and every single feature has a sample.

We want to use those in documentation snippets, without symlinking or "working around" docc decisions that force copying the same samples into Snippets/

Importance

Reduce code duplication as well as improve testing of snippets.

Alternatives Considered

No response

[d-ronnqvist]

This is related to, but not necessarily the same as, #1436.

Because this issue is about snippet extraction (which happens in the Swift-DocC Plugin) it might make sense to transfer the issue there but it also makes sense to keep it in DocC for now.

[heckj]

Definitely closely related. For a bit of reference, the existing/current process uses the directory Snippets as a well-known location, as the process currently flows:

  graph LR
      A[Build Snippets] --> B[Extract/Construct Snippet Symbol Graphs]
      B --> C[Include All Symbol Graphs for<br>DocC convert Processing of Catalogs]

Loading

So there's no orchestration (as yet) to load existing catalogs, determine where to find or what snippets it expects to find, and do appropriate orchestration to find, build, and transform relevant source files into symbol graphs for doing the full DocC convert today.