Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 18 commits into
base: main
Choose a base branch
from

Conversation

heckj
Copy link
Member

@heckj heckj commented Mar 5, 2025

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)

@heckj 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 d-ronnqvist added the documentation Improvements or additions to documentation label Mar 6, 2025
@d-ronnqvist
Copy link
Contributor

(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
Copy link
Member Author

heckj commented May 2, 2025

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

@heckj heckj requested a review from d-ronnqvist May 2, 2025 18:25
@heckj heckj force-pushed the snippets-docs branch from 6edd0fc to 9827d8b Compare May 2, 2025 21:21
@heckj
Copy link
Member Author

heckj commented May 2, 2025

@swift-ci please test

@heckj heckj self-assigned this May 6, 2025
@heckj
Copy link
Member Author

heckj commented May 7, 2025

@swift-ci please tests

@swiftlang swiftlang deleted a comment from d-ronnqvist May 7, 2025
Copy link
Contributor

@patshaughnessy patshaughnessy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

heckj commented May 9, 2025

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

@heckj heckj requested a review from patshaughnessy May 9, 2025 20:15
@heckj
Copy link
Member Author

heckj commented May 9, 2025

@swift-ci please test

@patshaughnessy
Copy link
Contributor

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
Copy link
Member Author

heckj commented May 22, 2025

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.

@heckj
Copy link
Member Author

heckj commented Jun 6, 2025

@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
Copy link
Member Author

heckj commented Jun 6, 2025

@swift-ci please test

Copy link
Contributor

@patshaughnessy patshaughnessy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

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

@heckj
Copy link
Member Author

heckj commented Jun 13, 2025

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
Copy link
Member Author

heckj commented Jun 13, 2025

@swift-ci please test

@heckj
Copy link
Member Author

heckj commented Jun 13, 2025

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!

@heckj heckj requested a review from d-ronnqvist June 16, 2025 20:27
@heckj heckj requested a review from d-ronnqvist June 17, 2025 17:47
@heckj heckj requested a review from d-ronnqvist June 23, 2025 14:36
@heckj
Copy link
Member Author

heckj commented Jun 25, 2025

@swift-ci please test

1 similar comment
@heckj
Copy link
Member Author

heckj commented Jun 26, 2025

@swift-ci please test

heckj and others added 18 commits July 11, 2025 16:19
Co-authored-by: Joe Heck <[email protected]>
Co-authored-by: Jacob Hearst <[email protected]>
…ence Syntax/Snippet.md

Co-authored-by: Pat Shaughnessy <[email protected]>
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.
@heckj
Copy link
Member Author

heckj commented Jul 11, 2025

(rebased and resolved the feedback - trimmed down some of the example, per David's feedback. Left the bits that Pat explicitly requested in)

@heckj
Copy link
Member Author

heckj commented Jul 11, 2025

@swift-ci please test

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants