Merge branch 'main' into extensions-to-external-types

Author: theMomax

README.md

@@ -250,7 +250,7 @@ active development and source stability is not guaranteed.
 Swift-DocC tracks all bug reports with 
 [GitHub Issues](https://github.com/apple/swift-docc/issues).
 When you submit a bug report we ask that you follow the
-[provided template](https://github.com/apple/swift-docc/issues/new?template=BUG_REPORT.md)
+[provided template](https://github.com/apple/swift-docc/issues/new?assignees=&labels=bug&template=BUG_REPORT.yml)
 and provide as many details as possible.
 
 > **Note:** You can use the [`environment`](bin/environment) script
@@ -268,7 +268,7 @@ that will help us track down the bug faster.
 ### Submitting a Feature Request
 
 For feature requests, please feel free to file a
-[GitHub issue](https://github.com/apple/swift-docc/issues/new?template=FEATURE_REQUEST.md)
+[GitHub issue](https://github.com/apple/swift-docc/issues/new?assignees=&labels=enhancement&template=FEATURE_REQUEST.yml)
 or start a discussion on the [Swift Forums](https://forums.swift.org/c/development/swift-docc).
 
 Don't hesitate to submit a feature request if you see a way

Sources/DocCDocumentation/DocCDocumentation.docc/Assets/link-to-source.png

@@ -24,17 +24,65 @@ Distributing your documentation involves the following steps:
 
 ### Generate a Publishable Archive of Your Documentation
 
-To create a documentation archive, use the `docc` command-line tool.
+To create a documentation archive for a Swift package, use the [SwiftPM DocC
+Plugin](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/)
+or use Xcode's _Build Documentation_ command.
 
-To export the documentation archive from the command line, run `docc` in Terminal. 
-
-For example, to build a documentation archive, use a command similar to the
-following:
+Alternatively, use the `docc` command-line tool directly, for example:
 
 ```shell 
-docc convert MyNewPackage.docc --fallback-display-name MyNewPackage --fallback-bundle-identifier com.example.MyNewPackage --fallback-bundle-version 1 --additional-symbol-graph-dir .build --output-dir MyNewPackage.doccarchive
+docc convert MyNewPackage.docc \
+  --fallback-display-name MyNewPackage \
+  --fallback-bundle-identifier com.example.MyNewPackage \
+  --fallback-bundle-version 1 \
+  --additional-symbol-graph-dir .build \
+  --output-dir MyNewPackage.doccarchive
+```
+
+#### Include links to your project's sources
+
+When publishing documentation to an audience that has access to your project's
+sources, e.g., for an open-source project hosted on GitHub, consider configuring
+DocC to automatically include links to the declarations of your project's symbols.
+
+For example, in the following screenshot, the "ParsableCommand.swift" link
+below the declaration navigates to the `ParsableCommand` declaration in the
+project's GitHub repository.
+
+![A DocC documentation page showing the title and declaration of a symbol
+called ParsableCommand. Under the declaration, there is a link with a Swift
+icon and the file name ParsableCommand.swift](link-to-source.png)
+
+To configure DocC to generate links to your project's sources, use the source
+service configuration flags like so:
+
+**GitHub**
+```bash
+docc convert […] \
+    --source-service github \
+    --source-service-base-url https://github.com/<org>/<repo>/blob/<branch> \
+    --checkout-path <path to local checkout>
+```
+
+**GitLab**
+```bash
+docc convert […] \
+    --source-service gitlab \
+    --source-service-base-url https://gitlab.com/<org>/<repo>/-/tree/<branch> \
+    --checkout-path <path to local checkout>
+```
+
+**BitBucket**
+```bash
+docc convert […] \
+    --source-service bitbucket \
+    --source-service-base-url https://bitbucket.org/<org>/<repo>/src/<branch> \
+    --checkout-path <path to local checkout>
 ```
 
+These arguments can also be provided to `swift package generate-documentation`
+if you're using the SwiftPM DocC Plugin or via the `OTHER_DOCC_FLAGS` build
+setting when building in Xcode.
 
 ### Send a Documentation Archive Directly to Developers
 

Sources/DocCDocumentation/DocCDocumentation.docc/Assets/link-to-source~dark.png

@@ -211,16 +211,18 @@ struct RenderContentCompiler: MarkupVisitor {
     mutating func visitBlockDirective(_ blockDirective: BlockDirective) -> [RenderContent] {
         switch blockDirective.name {
         case Snippet.directiveName:
-            let arguments = blockDirective.arguments()
-            guard let snippetURL = arguments[Snippet.Semantics.Path.argumentName],
-                  let snippetReference = resolveSymbolReference(destination: snippetURL.value),
+            guard let snippet = Snippet(from: blockDirective, for: bundle, in: context) else {
+                return []
+            }
+            
+            guard let snippetReference = resolveSymbolReference(destination: snippet.path),
                   let snippetEntity = try? context.entity(with: snippetReference),
                   let snippetSymbol = snippetEntity.symbol,
                   let snippetMixin = snippetSymbol.mixins[SymbolGraph.Symbol.Snippet.mixinKey] as? SymbolGraph.Symbol.Snippet else {
                 return []
             }
 
-            if let requestedSlice = arguments[Snippet.Semantics.Slice.argumentName]?.value,
+            if let requestedSlice = snippet.slice,
                let requestedLineRange = snippetMixin.slices[requestedSlice] {
                 // Render only the slice.
                 let lineRange = requestedLineRange.lowerBound..<min(requestedLineRange.upperBound, snippetMixin.lines.count)