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

[heckj]

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]

(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]>

[heckj]

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

[heckj]

@swift-ci please test

[heckj]

@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.

[heckj]

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

[heckj]

@swift-ci please test

[patshaughnessy]

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]

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.