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

[d-ronnqvist]

This page won't be displayed as long as the snippet symbol isn't in the symbol graph file of directives that this catalog uses.

To include it you'd need to remove this hiddenFromDocumentation = true line and then run swift run generate-symbol-graph in the DocC repo and commit the modified symbol graph file.

[heckj]

Thank you! I don't know how long it would have taken me to hunt down that detail without your guidance!

[d-ronnqvist]

It might be good to assume that the reader doesn't know the destination between a code snippet and a markdown code block element and lead with that information. A reader who finds this information might be overwhelmed of all the steps if all they want to do is to write a code block in their markup. That distinction might serve as a good segue to the benefits of compiled code examples which lets the reader make an informed decision about using code blocks or code snippets in their documentation.