[docs] Add basic documentation on using Snippets to DocC documentation #1166

heckj · 2025-03-05T18:40:45Z

Work towards resolving #417

Summary

Adds some base line documentation that describes how to use the snippets feature built in to DocC and the DocC Plugin.

how to add snippets to your project
how to run and verify the snippets
how to make slices in a snippet
how to reference the snippet, or a slice from a snippet, from within another DocC catalog entry

Dependencies & Testing

no dependencies
visually inspected with a local preview build of the DocC documentation for testing

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

Added tests (no tests, doc updates only)
Ran the ./bin/test script and it succeeded
Updated documentation if necessary

(this pull request is the combined work of https://github.com/JacobHearst and myself, I just happen to be submitting it)

d-ronnqvist · 2025-03-07T12:49:46Z

(this pull request is the combined work of https://github.com/JacobHearst and myself, I just happen to be submitting it)

FYI: You can coauthor commits by including a line like this in the commit message:

Co-authored-by: Jacob Hearst <[email protected]>

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md

Sources/docc/DocCDocumentation.docc/snippets.md

heckj · 2025-05-02T18:25:31Z

@JacobHearst @d-ronnqvist sorry for the delay in writing an overview. Added one based on @d-ronnqvist feedback, see what you think.

heckj · 2025-05-02T21:21:53Z

@swift-ci please test

heckj · 2025-05-07T16:50:49Z

@swift-ci please tests

patshaughnessy

This is a great! Thank you so much for writing these docs 👏 This is a very cool feature that most people aren't even aware of.

Just a curation issue and another minor tweak please.

Sources/docc/DocCDocumentation.docc/DocC Documentation.md

Sources/docc/DocCDocumentation.docc/snippets.md

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md

heckj · 2025-05-09T20:14:59Z

Thanks @patshaughnessy - accepted all suggestions and added a commit to rename the file per your suggestion.

heckj · 2025-05-09T20:15:14Z

@swift-ci please test

patshaughnessy · 2025-05-21T23:41:10Z

Hello @heckj - sorry for the delay.

I wasn't able to make this work following the instructions in your new article. I suspect that Swift DocC users have to add the Swift DocC Plugin as a dependency in their Package.swift, and then build the docs using the swift package generate-documentation CLI command. (Is there a way to use this feature from Xcode without SPM?)

Would you mind updating the article to show how to do this?

For example, the article might include details about these steps:

Create an example SPM project (e.g. "Hello World")
Add https://github.com/apple/swift-docc-plugin as a dependency
Create a snippet (you have this already)
Reference the snippet using the @Snippet directive (you have this already)
Build the docs using the Swift DocC Plugin (swift package generate-documentation)
View the snippet by opening a Ruby/Python web server from the subdirectory the plugin displays.

Without all of this information spelled out, I don't know how many readers will be able to use the feature successfully.

Let me know if you need help and I can push a draft of what this might look like.

heckj · 2025-05-22T02:40:01Z

Thanks for looking @patshaughnessy !

I don't think you strictly need the plugin to do this, but it's certainly easier than wrangling the independent steps of using docc on the command-line from the toolchain. I can (and will) revise to include your suggested path as a walk-through to make it easier for someone to use the features described.

To my knowledge, this capability hasn't been enabled with Xcode, and is only functional when building and rendering documentation using the Swift Package Manager. The core pieces for building the snippets are part of that project, and generally I do tend to add the swift-docc-plugin to a package when I'm working on such documentation.

Co-authored-by: Joe Heck <[email protected]> Co-authored-by: Jacob Hearst <[email protected]>

…a newline to the end of the file

…erated symbolgraph with that change

Co-authored-by: Pat Shaughnessy <[email protected]>

…ence Syntax/Snippet.md Co-authored-by: Pat Shaughnessy <[email protected]>

…dependency

heckj · 2025-06-06T20:47:23Z

@patshaughnessy I added in an early section explicitly calling out adding the swift-docc-plugin in order to view the snippets, but stopped short of adding sections that illustrate creating a project and making this more of a tutorial-like walkthrough, since that's not done for any of the other proximate documentation.

Give it a read and see what you think, and I'd happily take updates or a draft of what you'd like to see to make this easier to use. (I've also rebased this branch to catch it up a bit)

heckj · 2025-06-06T20:47:48Z

@swift-ci please test

make it clear where the snippets go, and also where the documentation catalog goes. Also show a concrete example of how to reference a snippet. Fix a typo.

patshaughnessy

Looks great thank you!

FYI I added a couple of things to your article that I hope will make things a bit more clear for readers:

An ASCII art diagram of where the files go. I was confused by how the Snippets folder goes under the root directory, while the documentation catalog goes under the Sources directory. I couldn't get it all working until I realized this.
A complete markdown example, showing how the module name goes in the @Snippet directory (as you explained) but also in the H1 tag at the top, which I forgot about.

Hope this helps!

FYI this bit didn't work for me:

DocC parses contiguous comments within the code of a snippet as markdown to annotate your code when embedded in documentation. DocC will attempt to reference symbols from within these comments just like any other documentation content. You can reference symbols from your API, which DocC converts into hyperlinks to that symbol when displaying the content.

I don't know if there's a bug, or if I misunderstood what you were saying. But we can figure that out later in another PR. This is a huge step forward in the docs, so let's merge it.

patshaughnessy · 2025-06-13T00:44:25Z

Let me know if my additions look good to you, and I'll merge it. Thanks again.

heckj · 2025-06-13T15:10:24Z

Looks great @patshaughnessy - Thanks for the additions!

No worries with the comments in snippets as markdown - happy to leave that to follow ups and just get the baseline docs out there!

heckj · 2025-06-13T15:10:31Z

@swift-ci please test

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

d-ronnqvist · 2025-06-13T15:26:08Z

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

+For example, use the command:
+
+```bash
+swift package add-dependency https://github.com/apple/swift-docc-plugin --from 1.1.0
+```
+
+Or edit your `Package.swift` to add the dependency:
+
+```
+let package = Package(
+    // name, platforms, products, etc.
+    dependencies: [
+        // other dependencies
+        .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0"),
+    ],
+    targets: [
+        // targets
+    ]
+)
+```


minor: I feel that we could defer to the plugin's README for this information.

d-ronnqvist

There's at least two issues that we should fix before merging this:

the parameter documentation is duplicated on the Snippet directive's page
the introduced version is different for the Snippet directive's page and the article about snippets.

heckj · 2025-06-13T16:15:12Z

Thanks David - I'll go back and revise to align properly and shift some of the content - hadn't clued into @ DirectiveArgumentWrapped - thanks for that reference!

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

d-ronnqvist · 2025-06-13T16:12:44Z

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

+In the example package above, the `YourProject.md` file might contain this markdown:
+
+```markdown
+# ``YourProject``
+
+Add a single sentence or sentence fragment, which DocC uses as the page’s abstract or summary.
+
+## Overview
+
+Add one or more paragraphs that introduce your content overview.
+
+This paragraph appears before the snippet.
+
+@Snippet(path: "YourProject/Snippets/example-snippet")
+
+This paragraph appears after the snippet.
+```


minor: AFAICT the main bit of information that this markdown example conveys is that snippets appear inline between paragraphs. If there's nothing more, I feel like it would both be clearer and more concise to spell that out explicitly.

d-ronnqvist · 2025-06-13T16:18:49Z

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

+This paragraph appears after the snippet.
+```
+
+Without any additional annotations in your snippet, Docc includes the entirety of your code example as the snippet.


minor: This sentence didn't make sense to me until I had read the rest of the paragraph.

Would it make sense to flip the order around and start with a problem statement and then how to solve it? For example:

If your snippet code requires setup—like imports or variable definitions—that distract from the snippet's main focus you can add // snippet.hide and // snippet.show lines in the snippet code to exclude the lines in between from displaying in your documentation.

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

d-ronnqvist · 2025-06-13T17:03:41Z

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

+Each code example file you create becomes it's own module.
+The name of the code example file you create is the name of the module that Swift creates.
+Use the `swift run` command in a terminal to compile and run the module to verify it compiles does what you expect.
+
+Run the earlier code example file named `example-snippet.swift` using the following command:
+
+```bash
+swift run example-snippet
+```


minor: I feel that this is technical on a level that the reader mostly isn't concerned with. IMO this is the why that explains the example below, but I would think the developer is more interested in how first.

Here's an alternate phrasing that focus on how without going into the module information:

You and consumers of your library can run your snippets from the command line using swift run snippet-name where "snippet-name" corresponds to a file name in your Snippets directory without the ".swift" file extension.

This section could also be a possible place for some of the information about imports from the section above. For example:

Your snippets can import targets defined in your local package, as well as products from its direct dependencies.
Each snippet is its own unit and can't access code from other snippet files.

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

d-ronnqvist · 2025-06-13T17:12:36Z

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

+### Preview your content
+
+Use the [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin) to preview content that includes snippets.
+To run the preview, use the following command from a terminal. 
+Replace `YourTarget` with a target from your package to preview:
+
+```bash
+swift package --disable-sandbox preview-documentation --target YourTarget
+```


minor: I'm not sure if this article needs to cover how to preview documentation. The main reason why I feel that it could be worth doing so is to call out that snippets only work with swift package [generate|preview]-documentation.

That's why it was added - @patshaughnessy walked through the article by itself, and wasn't able to get it to work because there's no support for Snippets in Xcode, which means you've got to go through the extended steps of generating everything on the CLI to get what you want - hence the longer description and more detail about "how to see your work", which is especially useful while you're assembling snippets and documentation together.

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

…an extension page

Sources/SwiftDocC/Semantics/Snippets/Snippet.swift

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

…ur-content.md Co-authored-by: David Rönnqvist <[email protected]>

heckj · 2025-06-25T22:03:02Z

@swift-ci please test

heckj · 2025-06-26T15:23:50Z

@swift-ci please test

heckj changed the title ~~Add basic documentation on using Snippets to DocC documentation~~ [docs] Add basic documentation on using Snippets to DocC documentation Mar 5, 2025

d-ronnqvist added the documentation Improvements or additions to documentation label Mar 6, 2025

d-ronnqvist reviewed Mar 7, 2025

View reviewed changes

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md Outdated Show resolved Hide resolved

d-ronnqvist reviewed Mar 7, 2025

View reviewed changes

Sources/docc/DocCDocumentation.docc/snippets.md Outdated Show resolved Hide resolved

heckj force-pushed the snippets-docs branch from fdccaf0 to 46f7556 Compare April 17, 2025 23:10

heckj requested a review from d-ronnqvist May 2, 2025 18:25

heckj force-pushed the snippets-docs branch from 6edd0fc to 9827d8b Compare May 2, 2025 21:21

heckj self-assigned this May 6, 2025

swiftlang deleted a comment from d-ronnqvist May 7, 2025

patshaughnessy requested changes May 9, 2025

View reviewed changes

heckj requested a review from patshaughnessy May 9, 2025 20:15

heckj and others added 10 commits June 6, 2025 13:43

Initial work on snippets documentation

fe94739

Co-authored-by: Joe Heck <[email protected]> Co-authored-by: Jacob Hearst <[email protected]>

consolidate copyright statements at bottom of markdown files and add …

cbf0291

…a newline to the end of the file

enables Snippet directive code for documentation, and updates the gen…

4aab5ea

…erated symbolgraph with that change

updating with an overview

5d61849

fixing license header for check script

9423044

Update Sources/docc/DocCDocumentation.docc/DocC Documentation.md

3e31e99

Co-authored-by: Pat Shaughnessy <[email protected]>

Update Sources/docc/DocCDocumentation.docc/snippets.md

b7f3c0f

Co-authored-by: Pat Shaughnessy <[email protected]>

Update Sources/docc/DocCDocumentation.docc/Reference Syntax/API Refer…

cd46790

…ence Syntax/Snippet.md Co-authored-by: Pat Shaughnessy <[email protected]>

renaming article per feedback

9febc3b

update documentation to explicitly call out adding swift-docc-plugin …

056f95f

…dependency

heckj force-pushed the snippets-docs branch from 438c334 to 056f95f Compare June 6, 2025 20:44

patshaughnessy added 2 commits June 12, 2025 17:25

Add an ASCII diagram of an example Swift package directory structure, to

8f3f186

make it clear where the snippets go, and also where the documentation catalog goes. Also show a concrete example of how to reference a snippet. Fix a typo.

Include a full markdown example containing @snippet

371ddad

patshaughnessy approved these changes Jun 13, 2025

View reviewed changes

d-ronnqvist reviewed Jun 13, 2025

View reviewed changes

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md Outdated Show resolved Hide resolved

d-ronnqvist reviewed Jun 13, 2025

View reviewed changes

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md Outdated Show resolved Hide resolved

d-ronnqvist reviewed Jun 13, 2025

View reviewed changes

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md Show resolved Hide resolved

d-ronnqvist reviewed Jun 13, 2025

View reviewed changes

d-ronnqvist requested changes Jun 13, 2025

View reviewed changes

d-ronnqvist reviewed Jun 13, 2025

View reviewed changes

applying updates based on David's feedback

6d54a00

heckj requested a review from d-ronnqvist June 16, 2025 20:27

co-locates snippet API ref content to source class rather than using …

ced4877

…an extension page

d-ronnqvist reviewed Jun 17, 2025

View reviewed changes

Sources/SwiftDocC/Semantics/Snippets/Snippet.swift Outdated Show resolved Hide resolved

revising note about snippets vs. docc catalogs and target linkage

1da9919

heckj requested a review from d-ronnqvist June 17, 2025 17:47

d-ronnqvist reviewed Jun 23, 2025

View reviewed changes

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md Outdated Show resolved Hide resolved

Update Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-yo…

8155e11

…ur-content.md Co-authored-by: David Rönnqvist <[email protected]>

heckj requested a review from d-ronnqvist June 23, 2025 14:36

removing section about markdown comments inside snippets

be45b48

[docs] Add basic documentation on using Snippets to DocC documentation #1166

Are you sure you want to change the base?

[docs] Add basic documentation on using Snippets to DocC documentation #1166

Uh oh!

Conversation

heckj commented Mar 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Dependencies & Testing

Checklist

Uh oh!

d-ronnqvist commented Mar 7, 2025

Uh oh!

Uh oh!

Uh oh!

heckj commented May 2, 2025

Uh oh!

heckj commented May 2, 2025

Uh oh!

heckj commented May 7, 2025

Uh oh!

patshaughnessy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

heckj commented May 9, 2025

Uh oh!

heckj commented May 9, 2025

Uh oh!

patshaughnessy commented May 21, 2025

Uh oh!

heckj commented May 22, 2025

Uh oh!

heckj commented Jun 6, 2025

Uh oh!

heckj commented Jun 6, 2025

Uh oh!

patshaughnessy left a comment

Choose a reason for hiding this comment

Uh oh!

patshaughnessy commented Jun 13, 2025

Uh oh!

heckj commented Jun 13, 2025

Uh oh!

heckj commented Jun 13, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

d-ronnqvist Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist left a comment

Choose a reason for hiding this comment

Uh oh!

heckj commented Jun 13, 2025

Uh oh!

Uh oh!

d-ronnqvist Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

d-ronnqvist Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

d-ronnqvist Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

heckj Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

heckj commented Mar 5, 2025 •

edited

Loading