apple/swift-docc-plugin

Swift Package Manager command plugin for Swift-DocC

Swift-DocC Plugin

The Swift-DocC plugin is a Swift Package Manager command plugin that supports building documentation for SwiftPM libraries and executables.

Usage

Please see the plugin's documentation for more detailed usage instructions.

Adding the Swift-DocC Plugin as a Dependency

To use the Swift-DocC plugin with your package, first add it as a dependency:

let package = Package(
    // name, platforms, products, etc.
    dependencies: [
        // other dependencies
        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.1.0"),
    ],
    targets: [
        // targets
    ]
)

Swift 5.6 is required in order to run the plugin.

Converting Documentation

You can then invoke the plugin from the root of your repository like so:

swift package generate-documentation

This will generate documentation for all compatible targets defined in your package and its dependencies and print the location of the resulting DocC archives.

If you'd like to generate documentation for a specific target and output that to a specific directory, you can do something like the following:

swift package --allow-writing-to-directory ./docs \
    generate-documentation --target MyFramework --output-path ./docs

Notice that the output path must also be passed to SwiftPM via the --allow-writing-to-directory option. Otherwise SwiftPM will throw an error as it's a sandbox violation for a plugin to write to a package directory without explicit permission.

Any flag passed after the generate-documentation plugin invocation is passed along to the docc command-line tool. For example, to take advantage of Swift-DocC's new support for hosting in static environments like GitHub Pages, you could run the following:

swift package --allow-writing-to-directory ./docs \
    generate-documentation --target MyFramework --output-path ./docs \
    --transform-for-static-hosting --hosting-base-path MyFramework

Previewing Documentation

The Swift-DocC plugin also supports previewing documentation with a local web server. However, unlike converting documentation, previewing is limited to a single target a time.

To preview documentation for the MyFramework target, you could run the following:

swift package --disable-sandbox preview-documentation --target MyFramework

To preview documentation for a product defined by one of your package's dependencies, you could run the following:

swift package --disable-sandbox preview-documentation --product OtherFramework

Hosting Documentation

For details on how to best build documentation for hosting online and a specific tutorial for publishing to GitHub Pages, please see the plugin's documentation.

Bug Reports and Feature Requests

Submitting a Bug Report

The Swift-DocC plugin tracks all bug reports with GitHub Issues. When you submit a bug report we ask that you follow the provided template and provide as many details as possible.

If you can confirm that the bug occurs when using the latest commit of the Swift-DocC plugin from the main branch, that will help us track down the bug faster.

Submitting a Feature Request

For feature requests, please feel free to file a GitHub issue or start a discussion on the Swift Forums.

Don't hesitate to submit a feature request if you see a way the Swift-DocC plugin can be improved to better meet your needs.

All user-facing features must be discussed in the Swift Forums before being enabled by default.

Contributing to the Swift-DocC Plugin

Please see the contributing guide for more information.

swift-docc-plugin's Issues

Failure to produce offline documentation if you consume C++ libraries via Swift C++/Interop

If you create a project that references a C++ library with the new swiftSettings: [.interoperabilityMode(.Cxx)]
mode in Package.swift, the system fails to generate symbols, which causes it to silently fail and produce
an incomplete documentation package.

Additionally, there is no warning issued, so you only find out about these problems much later on, from the
Web interface that merely produces an "Unknown error" message on the web.

This is new ground, I am using Xcode 15, beta 7, but the problem also happens with Xcode 15, beta 5.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

I have linked a simple repro here

Using this command should produce working documentation, in particular, you can tell if it worked because the directory /tmp/docs/documentation is present:

Clone the repro:

$ git clone https://github.com/migueldeicaza/SwiftDocCPlusPlusBug.git

When you run generate-documentation targeting /tmp/docs as the output directory:

$ swift package --allow-writing-to-directory /tmp/docs generate-documentation --target demo --disable-indexing --transform-for-static-hosting --hosting-base-path /SwiftNavigation --output-path /tmp/docs --diagnostic-level information

This should produce a directory in /tmp/docs/documentation and the symbols in .build/arm64-apple-macosx/extracted-symbols/demo/demo/demo.symbols.json

Actual behavior

Notice that /tmp/docs/documentation does not exist, and there is a warning:

/private/tmp/demo/Sources/demo/demo.docc/Documentation.md:1:3: warning: No symbol matched 'demo'. Can't resolve 'demo'.

Additionally the .build/arm64-apple-macosx/extracted-symbols/demo/demo directory is empty and lacks the demo.symbols.json

Steps to Reproduce

Small test case is here:

https://github.com/migueldeicaza/SwiftDocCPlusPlusBug

Instructions to reproduce the issue once cloned:

swift package --allow-writing-to-directory /tmp/docs generate-documentation --target demo --disable-indexing --transform-for-static-hosting --hosting-base-path /SwiftNavigation --output-path /tmp/docs --diagnostic-level information

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 26ac575 (1.3.0)
Swift Compiler version: swift-driver version: 1.87.1 Apple Swift version 5.9 (swiftlang-5.9.0.128.106 clang-1500.0.40.1)

Running the plugin using Xcode 13 produces error 'variable binding in a condition requires an initializer'

When trying to generate Documentation Using Xcode 13 from the main branch, 2 errors occur with the same message variable binding in a condition requires an initializer both in the Snippet Parser class of the Package. This does not occur when using the package with Xcode 14 (beta at the time of writing this)

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

Documentation to be generated when using Xcode 13

Actual behavior

Error (variable binding in a condition requires an initializer) is thrown.

Steps to Reproduce

Using the following command against the main branch of this repository causes the issue, it does not happen when using Xcode 14 or when pointing to the older 1.0.0 Release (but obviously this is old).

swift package --allow-writing-to-directory ./public generate-documentation --target JLRAnalytics --disable-indexing --output-path ./public --transform-for-static-hosting --hosting-base-path 'jlranalytics'

Swift-DocC Plugin Version Information

Swift-DocC plugin version: main
Swift Compiler version: swift-driver version: 1.45.2 Apple Swift version 5.6.1 (swiftlang-5.6.0.323.66 clang-1316.0.20.12) Target: x86_64-apple-macosx12.0

Is it possible to override where the plugin searches for the docc catalog

As I understand it the plugin expects to find the docc catalog inside the Source folder of the target. Would it be possible to add an option to point to a different location.

I am trying to add docc support to a Package.swift that is set to use swift-tools-version 5.3. I do this by adding the plugin dependency only if the swift version is 5.6 or greater

#if swift(>=5.6)
// Add the documentation compiler plugin if possible
package.dependencies.append(
    .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")
)
#endif

For the plugin to find my docc catalog I add it to the Sources/MyTarget folder. But I get the warning

Generating documentation for 'MyTarget'...
'my-target': warning: found 1 file(s) which are unhandled; explicitly declare them as resources or exclude from the target
    /Users/adamfowler/Developer/macOS/lib/my-target/Sources/MyTarget/MyTarget.docc

If exclude the MyTarget.docc folder from the target then the docc plugin doesn't find it.

If I could place the docc catalog outside of my Sources folder tree and tell the plugin where to find it. This would resolve the issue above.

[SR-15765] CLI option for choosing level of access to expose when assembling documentation for internal consumption

Previous ID	SR-15765
Radar	None
Original Reporter	@heckj
Type	Improvement

Additional Detail from JIRA

Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	None
Priority	Medium

md5: 1e2f20aa46123585b94e4a67226c6fb4

Issue Description:

The current `swift-docc-plugin` has some code to choose a level of protection to use when generating a symbol graph (apple/swift-docc-plugin/blob/main/Plugins/SharedPackagePluginExtensions/Target+defaultSymbolGraphOptions.swift#L16) - currently it's using `public` for libraries and `internal` for executables.

I'd like to be able to make this choice explicitly for the use case of generating internal documentation, so that libraries and/or executables could include not just `internal`, but also `private` methods that are documented.

I inquired in the forums about the potential to add a command line option to the swift-docc-plugin interface to allow this, and opening a bug was suggested as a means to dig into this.

I don't have a firm proposal for the CLI option name, but wanted to suggest `--access level` as a possible option. I was thinking this could either override the specific access level returned from `defaultSymbolGraphOptions` (preserving the other defaults it provides:

• includeSynthesized: true

• includeSPI: false
  ) or if the option was invoked could be explicitly checked and the options passed into `getSymbolGraph` within `SwfitDoccConvert`.

If it would be preferable to include three (optional!) command line options, one for each of the possible symbol graph options (access level, includeSynthesized, and includeSPI), I'd be happy to try and cobble that together as well, building off the defaults already in place. My initial instinct is that access level is the one that I'd like to be able expose for internal docs, but I also don't use the `SPI` marker within my libraries.

Support for binary targets

Feature Request: Support for binary targets

Description:

I make an xcframework, distributed as a SPM binary target. As far as I can tell, there is no way for me to incorporate DocC support for it directly in the package. I think it would be really nice to be able to incorporate documentation.

Motivation:

It is totally possible to get this to work out-of-band. But, especially with things like the Swift Package Index building and hosting documentation, finding a way to officially support it would be much more convenient. And, could also help encourage better documentation for binaries distributed this way.

Importance:

While my particular package is also open source, I think may binaries distributed this way are not. Encouraging better documentation for these cases would be really welcome.

Alternatives Considered

It is possible to get this to work with a custom solution, outside of SPM. But, its a pain, and doesn't work with existing tooling, particularly SPI.

error: no such module 'UIKit'

When I run this command in my project,
swift package generate-documentation

it is failed with the following error.

/Users/.../ProjectName/PackageName/Sources/.../ScreenCoordinateValue.swift:6:8: error: no such module 'UIKit'
import UIKit

What is wrong?

No symbols are extracted when generating documentation (w/ the CLI) while the package uses a local XCFramework reference

I ran into an odd situation where I when I attempted to use swift-docc-plugin to generate documentation archives (either converted for static HTML or the original DocC archives), the archives would end up with 0 symbols within them.

An example of this kind of project is OSS in github: automerge-swift and the relevant pieces that make the difference here is a local reference to an XCFramework. The relevant stanza of Package.swift to illustrate:

   .binaryTarget(
      name: "automergeFFI",
      path: "./automergeFFI.xcframework.zip"
    ),
    .target(
      name: "AutomergeUniffi",
      dependencies: ["automergeFFI"],
      path: "./AutomergeUniffi"
    ),
    .target(
      name: "Automerge",
      dependencies: ["AutomergeUniffi"]
    ),

I dug through this down into SwiftPM, where the symbols are extracted. The relevant process call to do the extraction isn't available using -v or -vv output from swift package, but is in the form of:

/Applications/Xcode-14.3_beta_2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift-symbolgraph-extract -module-name Automerge -target arm64-apple-macosx10.15 -I /Users/heckj/src/automerge-swifter/.build/arm64-apple-macosx/debug -sdk /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX13.3.sdk -F /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Frameworks -I /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/usr/lib -L /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/usr/lib -module-cache-path /Users/heckj/src/automerge-swifter/.build/arm64-apple-macosx/debug/ModuleCache -v -minimum-access-level public -skip-inherited-docs -omit-extension-block-symbols -output-dir /Users/heckj/src/automerge-swifter/temp

This script doesn't reference the local XCFramework directories at all, resulting in the whole extraction process failing with out propagating up a failure (as opposed to a "no symbols" scenario, which seems like a correct, non-failure response for an empty swift file kind of setup).

Building the package with this structure works without issue - so it seems that the core issue under the covers is that the extraction of symbols uses different logic to build up the includes, or pre-loads a module cache, where the symbol extraction doesn't do that. Therefore a workaround exists to run a build to explicitly pull our the symbols, and then run docc directly with a reference to that manually generated symbol cache.

This issue only appears to happen when using a local XCFramework reference. When using a binaryTarget with a remote reference and hash, it "does the right thing" with preloading a module cache or including the relevant directories (not sure which).

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

documentation archive to contain symbols

Actual behavior

documentation archives generated with any internal content, but no symbols are included within them.

Steps to Reproduce

The branch debug-docc-plugin on the repository https://github.com/heckj/automerge-swifter/ illustrates the issue with a script:

git clone https://github.com/automerge/automerge-swift -b debug-docc-plugin
cd automerge-swift
./scripts/build-xcframework.sh # NOTE: requires Rust to be installed to build this!
./test-docc-script.bash

Example output of script:

Building for debugging...
[54/54] Linking snippet-extract
Build complete! (4.26s)
Generating documentation for 'Automerge'...
symbol graph options: 'SymbolGraphOptions(minimumAccessLevel: PackagePlugin.PackageManager.SymbolGraphOptions.AccessLevel.public, includeSynthesized: true, includeSPI: false, emitExtensionBlocks: false)'
Building for debugging...
[15/15] Compiling Automerge value.swift
Build complete! (2.35s)
target symbol graph directory path: '/Users/heckj/Desktop/foo/automerge-swifter/.build/arm64-apple-macosx/extracted-symbols/automerge-swifter/Automerge'
snippet extractor provided, attempting to generate snippet symbol graph
no snippet symbol graphs generated
docc archive output path: '/Users/heckj/Desktop/foo/automerge-swifter/.build/plugins/Swift-DocC/outputs/Automerge.doccarchive'
docc invocation: '/Applications/Xcode-14.3_beta_2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc convert /Users/heckj/Desktop/foo/automerge-swifter/Sources/Automerge/Automerge.docc --fallback-bundle-identifier com.github.automerge.automerge-swifter --output-path ./docs --emit-digest --transform-for-static-hosting --hosting-base-path automerge-swifter --fallback-display-name Automerge --additional-symbol-graph-dir /Users/heckj/Desktop/foo/automerge-swifter/.build/arm64-apple-macosx/extracted-symbols/automerge-swifter/Automerge'
Converting documentation...
Conversion complete! (0.26s)
Generated DocC archive at '/Users/heckj/Desktop/foo/automerge-swifter/docs'
Generated        0 identifiers/symbols

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.1.0, and main (6a8f81a21df0aef44513f5ce25b58ae758347789)
Swift Compiler version: ```
swift-driver version: 1.75.1 Apple Swift version 5.8 (swiftlang-5.8.0.119.11 clang-1403.0.22.11.100)
Target: arm64-apple-macosx13.0

New `--include-extended-types` changes seems to break `--additional-symbol-graph-dir`

Prior to version 1.2, we were generating our docs using additional-symbol-graph-dir.
This is how we built the symbol graph:

sh("swift",
    "build",
    "--target", "RevenueCat",
    "--configuration", "debug", # Necessary for debug-only symbols
    # Build for iOS instead of the default macOS. This ensures that iOS-only symbols are included in the docs.
    "-Xswiftc", "-sdk", "-Xswiftc", sh("xcrun", "--sdk", "iphonesimulator", "--show-sdk-path").strip!,
    "-Xswiftc", "-target", "-Xswiftc", "x86_64-apple-ios#{ios_version}-simulator",
    "-Xswiftc", "-emit-symbol-graph",
    "-Xswiftc", "-emit-symbol-graph-dir",
    "-Xswiftc", ".build")

I updated the plugin to 1.2 to be able to use --include-extended-types now so that we can document our extensions. However, generating symbols fails now:

[207/229] Emitting module RevenueCat
<unknown>:0: error: error opening '.build/RevenueCat.symbols.json' for output: No such file or directory
<unknown>:0: error: error opening '.build/[email protected]' for output: No such file or directory
<unknown>:0: error: error opening '.build/[email protected]' for output: No such file or directory

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

I expected our swift build command to continue working

Actual behavior

Build fails.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.2.0
Swift Compiler version:

swift-driver version: 1.75.2 Apple Swift version 5.8 (swiftlang-5.8.0.124.2 clang-1403.0.22.11.100)
Target: arm64-apple-macosx13.0

Generated documentation could not be viewed on GitHub pages saying "The page you’re looking for can’t be found"

I used Swift-DocC plugin to preview documentation and it worked great. Then I followed instructions to publish documentation to GitHub pages, and when I try to view that, I get "The page you’re looking for can’t be found", while bottom bar is ok and there are no errors in browser network logs.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

Main page should be shown.

Actual behavior

"The page you’re looking for can’t be found" message is shown in bold at the center of the screen.

Steps to Reproduce

1. Clone https://github.com/tinkoff-mobile-tech/TinkoffConcurrency/tree/tech/documentation
2. Run swift package --allow-writing-to-directory docs generate-documentation --target TinkoffConcurrency --disable-indexing --transform-for-static-hosting --hosting-base-path '/TinkoffConcurrency' --output-path ./docs

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.2.0, latest main — results are the same.
Swift Compiler version: Output from swiftc --version.

swift-driver version: 1.62.15 Apple Swift version 5.7.2 (swiftlang-5.7.2.135.5 clang-1400.0.29.51)
Target: arm64-apple-macosx12.0

inconsistent recognition of the target provided to `preview-documentation`

Using docc-plugin 1.1.0, I'm seeing inconsistent results while running a preview command:

$(xcrun --find swift) package --disable-sandbox preview-documentation --target SwiftVizScale

In the best case, it does the right thing and the output that I get looks like:

Building for debugging...
Build complete! (0.15s)
Building for debugging...
Build complete! (0.12s)
Input: /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc
Template: /Applications/Xcode-14.3_beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
/Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc/Snippets.md:5:1: warning: Topic reference 'Scale/Snippets/ExampleSnippet' couldn't be resolved. No local documentation matches this reference.
========================================
Starting Local Preview Server
	 Address: http://localhost:8080/documentation/swiftvizscale
========================================
Monitoring /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc for changes...

But sometimes, the preview URL that's presented doesn't include the link to the target:

Building for debugging...
Build complete! (0.15s)
Building for debugging...
Build complete! (0.12s)
Input: /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc
Template: /Applications/Xcode-14.3_beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
/Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc/Snippets.md:5:1: warning: Topic reference 'Scale/Snippets/ExampleSnippet' couldn't be resolved. No local documentation matches this reference.
========================================
Starting Local Preview Server
	 Address: http://localhost:8080/
========================================
Monitoring /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc for changes...

I'm a little unclear on why it's showing up in some, but not others - but it's a bit of a challenge to remember the URL extension without it being provided. And when it doesn't show the link, the content doesn't appear to be available at the url http://localhost:8080/documentation/swiftvizscale.

In the cases where I get the shorter URL, the preview basically "just doesn't work" and the only workaround is to re-run the command until it does.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

swift package --disable-sandbox preview-documentation --target SwiftVizScale provides a URL that you can click on and shows you the contents.

Actual behavior

In some iterations of running this command, the url provided is Address: http://localhost:8080/ and no content is available even at the extended URL.

Steps to Reproduce

git clone https://github.com/swiftviz/Scale
cd Scale
swift package update
swift package --disable-sandbox preview-documentation --target SwiftVizScale

Repeat 3-5 times, killing the server and re-running the preview-documentationcommand. For me, it's resulting in the broken setup in a 1:2 to 1:3 ratio.

I have repeated this with the main branch as well as the 1.1.0 branch - same results.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.1.0 and branch: "main"
Swift Compiler version::

swift-driver version: 1.75.1 Apple Swift version 5.8 (swiftlang-5.8.0.117.11 clang-1403.0.22.8.60)
Target: arm64-apple-macosx13.0

Provide sensible defaults when using `--source-service` argument

docc added support for specifying information about the remote source repository where the project is hosted (e.g., its GitHub URL) in apple/swift-docc#256, so that it can automatically emit a link to the symbol's source code.

Example invocation:

swift package generate-documentation \
  --source-service github \
  --source-service-base-url https://github.com/<org>/<repo>/blob/main \
  --checkout-path <path to local checkout>

Since SwiftPM already has smarts about the repo in which the package resides, the plugin should be able to fill in some of the arguments above by default. For example, it could pass the root path of the current repository to the --checkout-path argument. Maybe it could also find the appropriate --source-service-base-url value by inspecting the git remote's URL. I'm not sure whether these values can be grabbed using the current plugin API—it's possible there it additional information that SwiftPM would need to surface to make this work.

Importance:

This feature would make it easier to automatically include links back to documented symbols' source code on remote source services like GitHub. It's not critical though, because the values you need pass to DocC are pretty much constant and can be provided via a wrapper script.

swift-docc-plugin produces documentation for last target only

Describe the bug
When using swift-docc-plugin to generate documentation any target's documentation will overwrite previously generated documentation. For example if a package has "TargetA" and "TargetB" and the command swift package --allow-writing-to-directory "./docs" generate-documentation --disable-indexing --output-path "./docs" --transform-for-static-hosting --hosting-base-path "PackageName" is run it will generate the documentation for "TargetA" and then "TargetB", but the documentation for "TargetB" will overwrite "TargetA".

To Reproduce
Steps to reproduce the behavior:

1. Create a package with multiple targets
2. Add swift-docc-plugin as a dependency
3. Run swift package --allow-writing-to-directory "./docs" generate-documentation --disable-indexing --output-path "./docs" --transform-for-static-hosting --hosting-base-path "PackageName"

Expected behavior
A directory suitable for static hosting should be generated, which contains the documentation for "TargetA" and "TargetB".

I think the root index.html should provide links to both of these targets, but I'm not sure if this is an expected feature or a new feature request.

Screenshots
N/A

Environment (please complete the following information):

• OS: macOS 12.3.1
• Xcode Version/Tag/Branch: 13.3.3
• swift-docc-plugin: 1.0.0

Additional context
N/A

Warning when building a package using the plugin with Swift 5.9.

In adding Swift 5.9 to the CI for swift-protobuf, we noticed some warning coming from the plugin compile:

https://github.com/apple/swift-protobuf/actions/runs/6249612455/job/16966661520?pr=1459

/__w/swift-protobuf/swift-protobuf/main/.build/checkouts/swift-docc-plugin/Plugins/Swift-DocC Convert/Symbolic Links/SharedPackagePluginExtensions/PackageExtensions.swift:31:17: warning: switch covers known cases, but 'TargetDependency' may have additional unknown values
                switch dependency {
                ^
/__w/swift-protobuf/swift-protobuf/main/.build/checkouts/swift-docc-plugin/Plugins/Swift-DocC Convert/Symbolic Links/SharedPackagePluginExtensions/PackageExtensions.swift:31:17: note: handle unknown values using "@unknown default"
                switch dependency {
                ^
[1/1] Compiling plugin Swift-DocC
/__w/swift-protobuf/swift-protobuf/main/.build/checkouts/swift-docc-plugin/Plugins/Swift-DocC Preview/Symbolic Links/SharedPackagePluginExtensions/PackageExtensions.swift:31:17: warning: switch covers known cases, but 'TargetDependency' may have additional unknown values
                switch dependency {
                ^
/__w/swift-protobuf/swift-protobuf/main/.build/checkouts/swift-docc-plugin/Plugins/Swift-DocC Preview/Symbolic Links/SharedPackagePluginExtensions/PackageExtensions.swift:31:17: note: handle unknown values using "@unknown default"
                switch dependency {
                ^

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

Clean compile.

Actual behavior

Warning generated.

Steps to Reproduce

Simply doing a build should produce the warnings.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.3.0
Swift Compiler version: 5.9

`--enable-inherited-docs` flag is undocumented

The help for this package (which by the way, I haven't been able to get to using swift help package) shows --enable-inherited-docs.
This seems to map to inheritDocs in Docc, but it appears that this flag isn't parsed at all.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

• --enable-inherited-docs is parsed and sent to Docc
• --enable-inherited-docs is documented

Actual behavior

This flag is unused.

Steps to Reproduce

Example command:

swift package --disable-sandbox --allow-writing-to-directory docs preview-documentation --target Target --disable-indexing --output-path docs --enable-inherited-docs --additional-symbol-graph-dir .build

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 5f2e247
Swift Compiler version:

swift-driver version: 1.62.15 Apple Swift version 5.7.1 (swiftlang-5.7.1.135.2 clang-1400.0.29.51)
Target: arm64-apple-macosx13.0

Snippet crash: No value associated with key 'chunks'

running a recent revision (00555b6efa14095243fbce031dba8a03cfc6333e) of this plugin on swift-json crashes with

/home/klossy/dev/swift-json/Sources/JSON/JSON.docc/json.md:1:1: warning: Unknown directive 'import'; this element will be ignored
/home/klossy/dev/swift-json/Sources/JSON/JSON.docc/json.md:2:1: warning: Unknown directive 'import'; this element will be ignored
/home/klossy/dev/swift-json/Sources/JSON/JSON.docc/json.md:1:1: warning: An article is expected to start with a top-level heading title
Error: keyNotFound(CodingKeys(stringValue: "chunks", intValue: nil), Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "symbols", intValue: nil), _JSONKey(stringValue: "Index 1", intValue: 1), CodingKeys(stringValue: "snippet", intValue: nil)], debugDescription: "No value associated with key CodingKeys(stringValue: \"chunks\", intValue: nil) (\"chunks\").", underlyingError: nil))

Generating documentation for 'LintingDictionary'...
error: 'docc convert' invocation failed with a nonzero exit code: '1'
error: unspecified("ExitCode(rawValue: 1)")

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

swift-json’s documentation was written for Biome, so i don’t expect this plugin to handle all of its documentation by default, but it should probably ignore the invalid snippets gracefully instead of crashing.

Actual behavior

already described above.

Steps to Reproduce

1. clone swift-json at 59d34c5f8c337b068d07ad5b0e4caa2fd0b8176e, and replace its docgen tool with:

.package(url: "https://github.com/apple/swift-docc-plugin", revision: "00555b6efa14095243fbce031dba8a03cfc6333e"),

2. run $ swift package generate-documentation

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 00555b6efa14095243fbce031dba8a03cfc6333e

$ swift --version
Swift version 5.8-dev (LLVM e41a0a126d143ae, Swift 23e5143d22cb768)
Target: x86_64-unknown-linux-gnu
$ swiftenv version
DEVELOPMENT-SNAPSHOT-2022-07-25-a 

[`./bin/test`] Allow skipping clone of `swift-docc` and `swift-docc-render-artifact`

From #21 (comment)

In some scenarios, running swift-docc-plugin tests against the built-in docc in the installed toolchain could save time. Add an option to ./bin/test to skip cloning swift-docc and swift-docc-render-artifact and setting the environment variables to use those.

Behavior:

If --skip-building-upstream-docc (or perhaps an environment variable) is set:

• Don't set the following:
  • SWIFT_DOCC_ROOT
  • SWIFT_DOCC_RENDER_ARTIFACT_ROOT
  • SWIFT_DOCC_BRANCH
  • SWIFT_DOCC_RENDER_ARTIFACT_BRANCH
• Don't clone swift-docc or swift-docc-render-artifact
• Also don't set:
  • DOCC_EXEC
  • DOCC_HTML_DIR

See the above mentioned pull request for new code that should be skipped in this case.

Docc cannot generate the documentation folder

Docc plugin is not able to generate the documentation folder for the target.

Checklist

I'm using the main branch before I was using 1.0.0

Expected behavior

Generate documentation folder.

Actual behavior

It finds my docc file but when I go to the archive folder there is no documentation which is the reason why I can't see the documentation correctly. I tested it with a custom symbol graph and it works but I'm not sure this plugin support graph. But It generates some simple package that I write!

Steps to Reproduce

swift package --allow-writing-to-directory ./docs
generate-documentation
--target TARGET
--output-path ./docs
--transform-for-static-hosting
--hosting-base-path TARGET
--disable-indexing

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.0.0 and main commit hash.
3303b16 , 6a6577a

Swift Compiler version: Output from swiftc --version.
swift-driver version: 1.62.8 Apple Swift version 5.7 (swiftlang-5.7.0.127.4 clang-1400.0.29.50)
Target: x86_64-apple-macosx12.0

package preview-documentation doesn't display pathing to docs target, and top-level page is throwing an error when resolving.

Description

Using the tools versioned with 5.7.0 release:

/Applications/Xcode-14.1beta3.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift package --disable-sandbox tools-version
5.7.0

(This is also with the swift-docc-plugin branch of main to get snippets to work.)

When I invoke swift package preview-documentation:

export DOCC_JSON_PRETTYPRINT=YES
om.github.heckj.DoccSnippetExample \
 $(xcrun --find swift) package \
     --disable-sandbox \
     preview-documentation \
     --target DoccSnippetExample

The preview no longer shows the extension of the target. The output I'm seeing is:

========================================
Starting Local Preview Server
	 Address: http://localhost:8000/
========================================

Where it used to display the full path to the target:
http://localhost:8000/documentation/doccsnippetexample/

That root page also displays an error when you try to access it:

``` Failed to load resource: the server responded with a status of 404 (Not Found) http://localhost:8000/data/documentation/doccsnippetexample.json ```

And when I looked into the directory structure, the json file is located inside the target - so I'm suspecting there's been a slight adjustment somewhere and parts aren't quite aligned for where swift-docc-render looks for JSON files.

In the on-disk directory, the JSON file for this page resides at:
docs/data/documentation/doccsnippetexample/doccsnippetexample.json and I'm thinking that the preview server and docs-render is expecting to find it at docs/data/documentation/doccsnippetexample.json.

I'm uncertain, but suspect these might be related (target directory and broken link with preview), so I'm including them into a single report, but I'm happy to break them up as well.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

No response

Actual behavior

No response

Steps To Reproduce

For a reproduction case:

clone the repo:

• git clone https://github.com/heckj/DoccSnippetExample
• cd DoccSnippetExample
• ./docpreview.bash

(which invokes:

export DOCC_JSON_PRETTYPRINT=YES

 $(xcrun --find swift) package \
     --disable-sandbox \
     preview-documentation \
     --target DoccSnippetExample

Swift-DocC Version Information

'5.7.0'

Swift Compiler Version Information

swift-driver version: 1.62.15 Apple Swift version 5.7.1 (swiftlang-5.7.1.134.3 clang-1400.0.29.51)
Target: arm64-apple-macosx12.0

Xcode 13 produces error `Cannot find type 'SnippetBuilder' in scope`

When trying to generate documentation from the main branch with Swift 5.6 an error message appears Cannot find type 'SnippetBuilder' in scope, this does not happen in 3e3305b

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

Documentation to be generated when using Swift 5.6

Actual behavior

Error Cannot find type 'SnippetBuilder' in scope is thrown

Steps to Reproduce

Using Swift 5.6 and running the command swift package generate-documentation against the main branch produces the error

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 5f2e247 (current HEAD -> main)
Swift Compiler version: swift-driver version: 1.45.2 Apple Swift version 5.6 (swiftlang-5.6.0.323.62 clang-1316.0.20.8)

Support for skipping synthesized symbols

Feature Request: Support for skipping synthesized symbols

Description:

The Swift compiler supports a -skip-synthesized-members argument which excludes synthesized symbols from symbol graph files. Synthesized symbols can lead to a large increase in number of documentation pages for some frameworks. We should have a way of generating documentation without synthesized symbols from the DocC plugin.

swift-docc-plugin generate-documentation results in empty docc catalog - no symbols - when using a local binary target/XCFramework

Swift-docc-plugin is failing to generate documentation for a swift package that is using a binaryTarget with a local reference to an XCFramework, which is provided to include a local static binary library (compiled from another language: Rust in this case)

possibly related, depending on the underlying logic used to get the symbol graphs - I found an issue with swift package dump-symbol-graph with the same package + local binary target setup, opened as apple/swift-package-manager#6162. If swift-docc-plugin relies on that functionality, that might be the underlying issue. I wasn't sure however, so I wanted to open this as well.

The command in question:

$(xcrun --find swift) package \
      --allow-writing-to-directory ./docs \
      generate-documentation \
      --fallback-bundle-identifier com.github.y-crdt.Yniffi \
      --fallback-bundle-version 0.16.1 \
      --target Yniffi \
      --output-path ./docs \
      --emit-digest \
      --disable-indexing \
      --transform-for-static-hosting \
      --hosting-base-path 'Yniffi'

Note that manually generating the symbol graphs and then invoking docc directly does work:

rm -rf .build .symbol-graphs
mkdir -p .symbol-graphs

$(xcrun --find swift) build --target Yniffi \
    -Xswiftc -emit-symbol-graph \
    -Xswiftc -emit-symbol-graph-dir -Xswiftc .symbol-graphs

$(xcrun --find docc) convert swift/scaffold/Documentation.docc \
    --fallback-display-name Yniffi \
    --fallback-bundle-identifier com.github.y-crdt.Yniffi \
    --fallback-bundle-version 0.16.1 \
    --additional-symbol-graph-dir .symbol-graphs \
    --emit-digest \
    --transform-for-static-hosting \
    --output-path ./docs \
    --hosting-base-path 'Yniffi'

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

• Documentation catalog generated with symbols

Actual behavior

• Documentation catalog is generated, but there are no linked symbols

./docs/linkable-entities.json contains only []
./docs/indexing-records.json contains only []

Steps to Reproduce

Note: full reproduction requires building the XCFramework locally - which currently requires Rust to be installed locally.

1. git clone https://github.com/heckj/y-uniffi.git
2. cd y-uniffi
3. git checkout yrs_16_2
4. cd lib
5. ./build-xcframework.sh
6. swift build # works correctly, no issues
7. run command to generate empty docs:

$(xcrun --find swift) package \
      --allow-writing-to-directory ./docs \
      generate-documentation \
      --fallback-bundle-identifier com.github.y-crdt.Yniffi \
      --fallback-bundle-version 0.16.1 \
      --target Yniffi \
      --output-path ./docs \
      --emit-digest \
      --disable-indexing \
      --transform-for-static-hosting \
      --hosting-base-path 'Yniffi'

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.1.0
Swift Compiler version:

swift-driver version: 1.75.1 Apple Swift version 5.8 (swiftlang-5.8.0.117.11 clang-1403.0.22.8.60)
Target: arm64-apple-macosx13.0

(Issue was also happening identically with swift 5.7 release)

Making this a plugin dependency for a project slows down builds and CI for many people who don't need to generate docs.

I realize this kinda challenges the whole premise of the plugin, so maybe you should consider recommending that people conditionalize their dependency on this plugin.

Text("Hoge", bundle: .module) fails to output static site

In the SwiftUI library, I have defined a structure that contains Text("Hoge", bundle: .module) in the body variable. In this case, the build fails when the static site is built with Makefile.
If Text("Hoge", bundle: .module) is replaced with Text("Hoge"), the build succeeds.
The following libraries are affected by this phenomenon.
https://github.com/KC-2001MS/OnboardingUI

Note: This error occurred in all releases, including the main repository and the latest version.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

The following command should output the static site of the project for the specified target in the specified path

DOCC_TARGET = hoge
DOCC_DIR = ./docs

.PHONY: docc
docc:
	swift package --allow-writing-to-directory $(DOCC_DIR) \
		generate-documentation --target $(DOCC_TARGET) \
		--disable-indexing \
		--transform-for-static-hosting \
		--hosting-base-path hoge \
		--output-path $(DOCC_DIR)

Actual behavior

Describe or copy/paste the behavior you observe.

swift package --allow-writing-to-directory ./docs \
		generate-documentation --target home \
		--disable-indexing \
		--transform-for-static-hosting \
		--hosting-base-path home \
		--output-path ./docs
warning: 'onboardingui': found 2 file(s) which are unhandled; explicitly declare them as resources or exclude from the target
    /Users/keisuke/Documents/オープンソース開発/OnboardingUI/Sources/OnboardingUI/Localizable.xcstrings
    /Users/keisuke/Documents/オープンソース開発/OnboardingUI/Sources/OnboardingUI/PrivacyInfo.xcprivacy
Building for debugging...
Build complete! (0.25s)
Generating documentation for 'OnboardingUI'...
warning: 'onboardingui': found 2 file(s) which are unhandled; explicitly declare them as resources or exclude from the target
    /Users/keisuke/Documents/オープンソース開発/OnboardingUI/Sources/OnboardingUI/Localizable.xcstrings
    /Users/keisuke/Documents/オープンソース開発/OnboardingUI/Sources/OnboardingUI/PrivacyInfo.xcprivacy
Building for debugging...
/Users/keisuke/Documents/オープンソース開発/OnboardingUI/Sources/OnboardingUI/UI/View/Parts/OnboardingButton.swift:52:39: error: type 'Bundle?' has no member 'module'
            Text("Continue", bundle: .module)
                                     ~^~~~~~
error: fatalError

error: unspecified("fatalError")
make: *** [docc] Error 1

This is the actual representation in the above repository.

Steps to Reproduce

1. Download the following repository
2. Check that line 52 of OnboardingButton.swift is Text("Continue", bundle: .module)
3. Go to the folder of this repository in Terminal and execute make docc.
4. rewrite line 52 as Text("Continue") and repeat the action in 3.
   Check for errors in 3 and 4, respectively.

Workaround

Temporarily rewrite Text("Hoge", bundle: .module) to Text("Hoge") when outputting a static site.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.3.0 1.2.0 1.1.0 1.0.0 main
Swift Compiler version: swift-driver version: 1.87.3 Apple Swift version 5.9.2 (swiftlang-5.9.2.2.56 clang-1500.1.0.2.5).

PS

My apologies if I am using this incorrectly. I would appreciate it if you could point it out to me.

Rebuild docs when snippet changes.

Description

When previewing docs with the swift package preview-documentation I have found that changes made to snippet files (in the Snippets root directory) do not trigger a rebuild of docs. This makes it hard to iterate on documentation that uses snippets.

Further, I found found that snippets in the generated docs will update unless the preview server is stopped and restarted. For example, I can perform the following steps:

• Start the preview server for my docs (i.e. swift package preview-documentation)
• Open docs and confirm everything is running correctly
• Make a change to a snippet file in the Snippets directory
• Make a change to a documentation file
• Confirm that the docs did rebuild in Terminal
• Open the docs and see the old version of the snippet.

The only way to see the newest version of the snippet is to stop the preview server and start it again.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

I would hope that any changes to a snippet file or the main docs would rebuild all of the docs with the freshest version of all snippets.

Actual behavior

Snippets are not re-generated unless I stop the preview server and restart it.

Steps To Reproduce

No response

Swift-DocC Version Information

1.2.0

Swift Compiler Version Information

swift-driver version: 1.75.2 Apple Swift version 5.8.1 (swiftlang-5.8.0.124.5 clang-1403.0.22.11.100)
Target: arm64-apple-macosx13.0

Ability to generate Objective-C docs for Swift symbols

Feature Request: generate Objective-C documentation

Description:

When generating docs through Xcode, you can enable the DOCC_EXTRACT_OBJC_INFO_FOR_SWIFT_SYMBOLS build setting to get Objective-C documentation generated for Swift files.

I haven't found a way to achieve the same thing through this plugin, but the last comment in this thread (from March '22) says:

a further update with instructions will be shared once Objective-C doc generation can be used end-to-end. Also, one next step here will be to integrate this in the new DocC SwiftPM plugin 18.

https://forums.swift.org/t/extending-swift-docc-to-support-objective-c-documentation/53243/17

Motivation:

Being able to generate Objective-C symbols is very useful to the still large number of Objective-C developers out there.

Alternatives Considered

The alternative to this is to go back to the flow of generating the archive through Xcode, which would be a bummer since the plugin is a lot more useful.

generated docs only report: "An unknown error occurred."

Docs generated with swift-docc-plugin always result in a page showing only: An unknown error occurred. as can be seen on https://dastrobu.github.io/AccelerateArray/

The docs are generated without error or waring from the following steps:

/Users/runner/hostedtoolcache/swift-macOS/5.9/x64/usr/bin/swift --version
Apple Swift version 5.9 (swift-5.9-RELEASE)
Target: x86_64-apple-macosx12.0


swift package  --allow-writing-to-directory ./docs  generate-documentation  --output-path ./docs  --hosting-base-path AccelerateArray  --disable-indexing  --transform-for-static-hosting
  shell: /bin/bash -e {0}
  env:
    TOOLCHAINS: swift 5.9
  
Fetching https://github.com/apple/swift-docc-plugin
[1/1433] Fetching swift-docc-plugin
Fetched https://github.com/apple/swift-docc-plugin (1.22s)
Fetching https://github.com/apple/swift-docc-symbolkit
[1/2359] Fetching swift-docc-symbolkit
Fetched https://github.com/apple/swift-docc-symbolkit (1.18s)
Computing version for https://github.com/apple/swift-docc-symbolkit
Computed https://github.com/apple/swift-docc-symbolkit at 1.0.0 (0.72s)
Creating working copy for https://github.com/apple/swift-docc-symbolkit
Working copy of https://github.com/apple/swift-docc-symbolkit resolved at 1.0.0
Creating working copy for https://github.com/apple/swift-docc-plugin
Working copy of https://github.com/apple/swift-docc-plugin resolved at main
Building for debugging...
[1/39] Emitting module SymbolKit
[2/50] Compiling SymbolKit SourceOrigin.swift
[3/50] Compiling SymbolKit GenericConstraints.swift
[4/50] Compiling SymbolKit Swift.swift
[5/50] Compiling SymbolKit SemanticVersion.swift
[6/50] Compiling SymbolKit AccessControl.swift
[7/50] Compiling SymbolKit Availability.swift
[8/50] Compiling SymbolKit AvailabilityItem.swift
[9/50] Compiling SymbolKit Domain.swift
[10/50] Compiling SymbolKit DeclarationFragments.swift
[11/50] Compiling SymbolKit Fragment.swift
[12/50] Compiling SymbolKit FragmentKind.swift
[13/50] Compiling SymbolKit FunctionParameter.swift
[14/50] Compiling SymbolKit FunctionSignature.swift
[15/50] Compiling SymbolKit Identifier.swift
[16/50] Compiling SymbolKit KindIdentifier.swift
[17/50] Compiling SymbolKit Location.swift
[18/50] Compiling SymbolKit Mutability.swift
[19/50] Compiling SymbolKit Names.swift
[20/50] Compiling SymbolKit SPI.swift
[21/50] Compiling SymbolKit Snippet.swift
[22/50] Compiling SymbolKit Extension.swift
[23/50] Compiling SymbolKit GenericConstraint.swift
[24/50] Compiling SymbolKit Mixin+Equals.swift
[25/50] Compiling SymbolKit Mixin+Hash.swift
[26/50] Compiling SymbolKit Mixin.swift
[27/50] Compiling SymbolKit LineList.swift
[28/50] Compiling SymbolKit Position.swift
[29/50] Compiling SymbolKit SourceRange.swift
[30/50] Compiling SymbolKit Metadata.swift
[31/50] Compiling SymbolKit Module.swift
[32/50] Compiling SymbolKit OperatingSystem.swift
[33/50] Compiling SymbolKit Platform.swift
[34/50] Compiling SymbolKit Relationship.swift
[35/50] Compiling SymbolKit RelationshipKind.swift
[36/50] Compiling Snippets Snippet.swift
[37/50] Emitting module Snippets
[38/50] Compiling Snippets SnippetParser.swift
[39/50] Compiling SymbolKit GenericParameter.swift
[40/50] Compiling SymbolKit Generics.swift
[41/50] Compiling SymbolKit Namespace.swift
[42/50] Compiling SymbolKit Symbol.swift
[43/50] Compiling SymbolKit SymbolKind.swift
[44/50] Compiling SymbolKit SymbolGraph.swift
[45/50] Compiling SymbolKit GraphCollector.swift
[46/50] Compiling SymbolKit UnifiedSymbol+Encodable.swift
[47/50] Compiling SymbolKit UnifiedSymbol.swift
[48/50] Compiling SymbolKit UnifiedSymbolGraph+Encodable.swift
[49/50] Compiling SymbolKit UnifiedSymbolGraph.swift
[50/54] Compiling snippet_extract URL+Status.swift
[51/54] Compiling snippet_extract SymbolGraph+Snippet.swift
[52/54] Compiling snippet_extract SnippetBuildCommand.swift
[53/54] Emitting module snippet_extract
[53/54] Linking snippet-extract
Build complete! (32.64s)
Building for debugging...
[1/4] Compiling AccelerateArray internal.swift
[2/4] Compiling AccelerateArray cblas.swift
[3/4] Compiling AccelerateArray lapack.swift
[4/4] Emitting module AccelerateArray
[5/5] Compiling AccelerateArray vDSP.swift
Build complete! (29.06s)
Generating documentation for 'AccelerateArray'...
Converting documentation...
Conversion complete! (0.19s)
Generated DocC archive at '/Users/runner/work/AccelerateArray/AccelerateArray/docs'

What I am missing personally the most is a way to troubleshoot this error.
Being also a web developer, I would like to be able to get unminifed javascript, showing what is actually going wrong or some flags to generated the web app with some console logs pointing me at what is going wrong.

Solving the issue with my package is just one thing. Enabling the docc plugin for better trouble shooting would be the long term goal.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

It shows the same result as when running locally with

swift package --disable-sandbox preview-documentation

Actual behavior

shows: An unknown error occurred.

Generated docs can be found in: https://github.com/dastrobu/AccelerateArray/tree/gh-pages

Steps to Reproduce

1. clone or fork https://github.com/dastrobu/AccelerateArray
2. generate the docs as in https://github.com/dastrobu/AccelerateArray/blob/main/.github/workflows/docc.yaml
3. serve the docs from a GitHub page

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.3.0 and main
Swift Compiler version: Output from swiftc --version.

Apple Swift version 5.9 (swift-5.9-RELEASE)
Target: x86_64-apple-macosx12.0

see https://github.com/dastrobu/AccelerateArray/actions/runs/7241167505/job/19724963804

Cannot Specify Platform For Documents Generation

Currently we cannot specify the build platform for swift-docc-plugin. This means that the generate-documentation command only generates documentation for macOS. We hope that in the future there can be a -platform flag to allow document generation for a specific platform.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

There can be a -platform flag to allow document generation for a specific platform. For example, we can generate documents for iOS platform or tvOS platform.

Actual behavior

The generate-documentation command only generates documentation for macOS.

Steps to Reproduce

Run swift package generate-documentation, it is no possible to specify the platform information.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 5f2e247
Swift Compiler version:
swift-driver version: 1.62.15 Apple Swift version 5.7.1 (swiftlang-5.7.1.135.2 clang-1400.0.29.51)
Target: arm64-apple-macosx13.0

error: Plugin does not have access to a tool named ‘docc’

I have this error when running this commande : swift package generate-documentation

error: Plugin does not have access to a tool named ‘docc’

Preview Documentation reports error on exit

When running swift package --disable-sandbox preview-documentation --target <TARGET> on the command line, you would typically use CTRL-C to exit the command cleanly. This currently reports error: 'docc preview' invocation failed with a nonzero exit code: '9'.

This should probably be handled correctly and exit with code 0

req: dead link checking command for plugin

Feature Request: Dead Link checking command

Description:

Related to apple/swift-docc#701, it would be nice to have a docc-plugin command, or potentially a build plugin, that could parse HTML links from within DocC content to determine if those links were still valid or not.

When/if Docc emits a digest with all possible links within it, a useful follow-on would be a docc-plugin command to check those links to report which are valid/invalid, with sufficient location information in the output to know where/what file to update.

Motivation:

Early (and still current as of this writing) DocC doesn't have the ability to provide cross-references to modules or symbols in other modules, leading to the common practice of embedding URLs for the reader's convenience. URLs and libraries change, as well as even hosting locations, so URLs aren't always as static as we'd like. Ideally, one could run a process to verify that all external links, at least at a given point in time, are still valid links.

Importance:

This is primarily a quality of life improvement, and an efficiency update to the alternative of crawling all the pages generated with a javascript-aware-and-enabled parsing engine to view the HTML for links, following them, and report on failures.

Alternatives Considered

If you considered alternative approaches for this feature, please include them here.

/cc @amartini51

GitHub hosted pages fail to load function pages

I am generating documentation for static hosting on GitHub Pages and while I can try the result locally with a python server, when hosted on GitHub, some pages do not render, it looks like they are pages with '_' in their name.

The error is "The page you’re looking for can’t be found"

Navigate to this page:

https://migueldeicaza.github.io/SwiftGodotDocs/documentation/swiftgodot/node/

Then look for the "func _enterTree()" and click on that, which should be this url:

https://migueldeicaza.github.io/SwiftGodotDocs/documentation/swiftgodot/node/_entertree()

This will fail with a 404 for https://migueldeicaza.github.io/SwiftGodotDocs/data/documentation/swiftgodot/node/_entertree().json

You can see that the file has been posted to GitHub:

https://github.com/migueldeicaza/SwiftGodotDocs/blob/main/docs/data/documentation/swiftgodot/node/_entertree().json

But it looks like this does not get deployed or is accessible from the deployed GitHub pages.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

Actual behavior

The page should be visible.

Steps to Reproduce

git clone https://github.com/migueldeicaza/SwiftGodot.git
mkdir SwiftGodotDocs
cd SwiftGodot
make build-docs && make push-docs

Then push the above "SwiftGodotDocs" to a GitHub repo that can host Pages.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.3.0 for example, or a commit hash.
Swift Compiler version: swift-driver version: 1.87.1 Apple Swift version 5.9 (swiftlang-5.9.0.128.108 clang-1500.0.40.1)

No way to cleanly exit `swift package preview-documentation`

Description

Running docc preview builds the content, starts a local preview server, and then monitors the input directory for changes. Pressing control-C (SIGINT) stops the preview server and returns an exit code of zero to the calling process.

However, running swift package --disable-sandbox preview-documentation --target MyTarget returns a non-zero exit code when stopping the server with control-C (SIGINT) or control-\ (SIGQUIT).

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Swift-DocC Version Information

No response

Swift Compiler Version Information

swift-driver version: 1.62.8 Apple Swift version 5.7 (swiftlang-5.7.0.127.4 clang-1400.0.29.50)
Target: arm64-apple-macosx12.0

Add support for ObjC/C Package

Add support for ObjC/C Package

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

Generate docc preview successfully.

Actual behavior

error: target 'XX' is not a Swift source module

Steps to Reproduce

1. Init an empty C Package and add Documentation Catalog(XX.docc foloder).
2. Add Swift-DocC-Plugin depenedency
3. Run swift package --disable-sandbox preview-documentation --target XX

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.1.0
Swift Compiler version:

swift-driver version: 1.75.2 Apple Swift version 5.8 (swiftlang-5.8.0.124.2 clang-1403.0.22.11.100)
Target: arm64-apple-macosx13.0