Incorrect source link for documentation

[Kyle-Ye]

Which package(s) are showing incorrect data?

• https://swiftpackageindex.com/openswiftuiproject/openswiftui

Please explain what data is incorrect and what you expected to see

The source link of this page https://swiftpackageindex.com/openswiftuiproject/openswiftui/main/documentation/openswiftui/environmentkey should point to https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/main/Sources/OpenSwiftUI/Data/Environment/EnvironmentKey.swift#8 instead of https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/main/Sources/OpenSwiftUI/DataAndStorage/EnvironmentValues/EnvironmentKey.swift#L9

If the problem relates to the compatibility matrix, does it apply to specific builds?

None

Screenshots

None

Additional context

Unlike the last bug result which is due to the main branch documentation update was not timely within 24 hours.

https://github.com/SwiftPackageIndex/SwiftPackageIndex-Server/issues/2794#issuecomment-1871853741

This time, the relevant code has not been changed for a long time and the documentation on the main branch has been built and updated recently by SPI.

[finestructure]

Your docs aren't actually being generated at the moment, because your package is set to tools version 5.10 while in .spi.yml you set doc generation to run with 5.9.

I've openen PR to fix this: https://github.com/OpenSwiftUIProject/OpenSwiftUI/pull/93

[finestructure]

Note that this might not fix everything, because when I preview your docs locally, all I get is a tutorial page without any links:

I generated the docs via

env DEVELOPER_DIR=/Applications/Xcode-15.3.0.app xcrun swift package --disable-sandbox preview-documentation -p 8080 --target OpenSwiftUI

with the following appended to your Package.swift:

package.dependencies.append(
    .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")
)

[Kyle-Ye]

Note that this might not fix everything, because when I preview your docs locally, all I get is a tutorial page without any links:

That's expected. Still working in progress of it.

[Kyle-Ye]

I've openen PR to fix this: https://github.com/OpenSwiftUIProject/OpenSwiftUI/pull/93

Thanks. I've merged the PR.

I'll verify and close the issue when a new doc build is triggered and the main branch doc is updated.

[Kyle-Ye]

Your docs aren't actually being generated at the moment, because your package is set to tools version 5.10 while in .spi.yml you set doc generation to run with 5.9.

Suggestion: I would expect some error message/fail status for such mismatch instead of silently failing.

[Kyle-Ye]

Your docs aren't actually being generated at the moment, because your package is set to tools version 5.10 while in .spi.yml you set doc generation to run with 5.9.

After merging the PR into main, the doc is still not updated. Could you help give another look since I do not have the doc build log? @finestructure

[finestructure]

We do have build logs: https://swiftpackageindex.com/builds/9F1239BD-04D1-460B-83E1-BAD5458BBD75

You can find them on the build results page and the documentation ones are indicated with a little icon:

Note that the status is the build status and can be a success even if doc gen failed (which it did):

Error while generating docs: Error Domain=NSCocoaErrorDomain Code=260 "The folder “documentation” doesn’t exist." UserInfo={NSFilePath=/Users/builder/builds/TDmZkXJm/0/finestructure/swiftpackageindex-builder/spi-builder-workspace/.docs/openswiftuiproject/openswiftui/main/documentation, NSUserStringVariant=(
    Folder
), NSUnderlyingError=0x6000038ace40 {Error Domain=NSOSStatusErrorDomain Code=-43 "fnfErr: File not found"}}

[Kyle-Ye]

I can build the package's doc successfully locally using Xcode.

I can't understand what the error message "The folder “documentation” doesn’t exist." means.

Could you share a more detailed log or a complete doc build command so that I can try to reproduce locally and fix it on my side.

[finestructure]

I think the problem is that you seem to be generating a tutorial exclusively, i.e. without any other docs.

Here's your project's doc archive:

❯ ll /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/26372E68-3734-4A43-BF16-0675270B19B9/checkout/.docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41/
.rw-r--r--   40 sas 18 May 09:47 assets.json
drwxr-xr-x    - sas 18 May 09:47 css
drwxr-xr-x    - sas 18 May 09:47 data
.rw-r--r--  13k sas 18 May 09:47 developer-og-twitter.jpg
.rw-r--r--  13k sas 18 May 09:47 developer-og.jpg
.rw-r--r-- 4.0k sas 18 May 09:47 diagnostics.json
drwxr-xr-x    - sas 18 May 09:47 downloads
.rw-r--r--  15k sas 18 May 09:47 favicon.ico
.rw-r--r-- 1.5k sas 18 May 09:47 favicon.svg
drwxr-xr-x    - sas 18 May 09:47 images
drwxr-xr-x    - sas 18 May 09:47 img
drwxr-xr-x    - sas 18 May 09:47 index
.rw-r--r-- 1.1k sas 18 May 09:47 index.html
.rw-r--r--  559 sas 18 May 09:47 indexing-records.json
drwxr-xr-x    - sas 18 May 09:47 js
.rw-r--r--   40 sas 18 May 09:47 linkable-paths.json
.rw-r--r--  116 sas 18 May 09:47 metadata.json
.rw-r--r--    0 sas 18 May 09:47 theme-settings.json
drwxr-xr-x    - sas 18 May 09:47 tutorials
drwxr-xr-x    - sas 18 May 09:47 videos

and here's the archive for a test project:

❯ ll /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/D8301869-AD28-44CB-A325-E28AC92C6FEB/checkout/.docs/finestructure/builder-test-project/issue-2371/
.rw-r--r--   40 sas 18 May 09:51 assets.json
drwxr-xr-x    - sas 18 May 09:51 css
drwxr-xr-x    - sas 18 May 09:51 data
.rw-r--r--  13k sas 18 May 09:51 developer-og-twitter.jpg
.rw-r--r--  13k sas 18 May 09:51 developer-og.jpg
.rw-r--r--    2 sas 18 May 09:51 diagnostics.json
drwxr-xr-x    - sas 18 May 09:51 documentation
drwxr-xr-x    - sas 18 May 09:51 downloads
.rw-r--r--  15k sas 18 May 09:51 favicon.ico
.rw-r--r-- 1.5k sas 18 May 09:51 favicon.svg
drwxr-xr-x    - sas 18 May 09:51 images
drwxr-xr-x    - sas 18 May 09:51 img
drwxr-xr-x    - sas 18 May 09:51 index
.rw-r--r--  922 sas 18 May 09:51 index.html
.rw-r--r--  257 sas 18 May 09:51 indexing-records.json
drwxr-xr-x    - sas 18 May 09:51 js
.rw-r--r--   41 sas 18 May 09:51 linkable-paths.json
.rw-r--r--  134 sas 18 May 09:51 metadata.json
.rw-r--r--    0 sas 18 May 09:51 theme-settings.json
drwxr-xr-x    - sas 18 May 09:51 videos

Notice how you project's doc archive has no documentation folder.

We may be making assumptions about the presence of that folder in order to merge doc archives for different targets. I'll have to confirm that and see if they can be loosened. But I suspect this would go away if your doc gen included "regular" documentation.

[finestructure]

Here's the doc gen command we run:

env DEVELOPER_DIR=/Applications/Xcode-15.3.0.app xcrun swift package --allow-writing-to-directory .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 generate-documentation --emit-digest --disable-indexing --output-path .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --hosting-base-path openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --source-service github --source-service-base-url https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --checkout-path $PWD --target OpenSwiftUI

[Kyle-Ye]

Notice how you project's doc archive has no documentation folder.

Got it. But the package should have documentation actually. There are many symbols under OpenSwiftUI module eg. OpenSwiftUI.View.

Here's the doc gen command we run:

env DEVELOPER_DIR=/Applications/Xcode-15.3.0.app xcrun swift package --allow-writing-to-directory .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 generate-documentation --emit-digest --disable-indexing --output-path .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --hosting-base-path openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --source-service github --source-service-base-url https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --checkout-path $PWD --target OpenSwiftUI

Thanks. I'll try to reproduce it and report back later.

[finestructure]

Running this locally (with our mechanism) reveals a few doc related warnings that might be relevant:

========================================
GenerateDocs
========================================
Generating docs at path:  $workDir/.docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41
Repository:               OpenSwiftUIProject/OpenSwiftUI
Swift version used:       5.10
🖥️ bash -c shopt -s nullglob && for manifest in Package.swift Package@*.swift ; do
if ! grep -i "https://github.com/apple/swift-docc-plugin" "$manifest" ; then
cat <<EOF >> "$manifest"

package.dependencies.append(
    .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")
)
EOF
fi
done
Target:                   OpenSwiftUI
🖥️ env DEVELOPER_DIR=/Applications/Xcode-15.3.0.app xcrun swift package --allow-writing-to-directory .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 generate-documentation --emit-digest --disable-indexing --output-path .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --hosting-base-path openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --source-service github --source-service-base-url https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --checkout-path /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/C3ADD938-A55A-47F3-B006-C75A0D961092/checkout --target OpenSwiftUI
Generating documentation for 'OpenSwiftUI'...
Converting documentation...
warning: No symbol matched 'App'. Can't resolve 'App'.
 --> AppStructure/AppOrganization/App.md:1:3-1:10
1 + # ``App``
2 |
3 | ## Topics
warning: No symbol matched 'Binding'. Can't resolve 'Binding'.
 --> DataAndStorage/ModelData/Binding.md:1:3-1:14
1 + # ``Binding``
2 |
3 | ## Topics
warning: No symbol matched 'DynamicProperty'. Can't resolve 'DynamicProperty'.
 --> DataAndStorage/ModelData/DynamicProperty.md:1:3-1:22
1 + # ``DynamicProperty``
2 |
3 | ## Topics
warning: No symbol matched 'ObservedObject'. Can't resolve 'ObservedObject'.
 --> DataAndStorage/ModelData/ObservedObject.md:1:3-1:21
1 + # ``ObservedObject``
2 |
3 | ## Topics
warning: No symbol matched 'State'. Can't resolve 'State'.
 --> DataAndStorage/ModelData/State.md:1:3-1:12
1 + # ``State``
2 |
3 | ## Topics
warning: No symbol matched 'StateObject'. Can't resolve 'StateObject'.
 --> DataAndStorage/ModelData/StateObject.md:1:3-1:18
1 + # ``StateObject``
2 |
3 | ## Topics
warning: No symbol matched 'PreferenceKey'. Can't resolve 'PreferenceKey'.
 --> DataAndStorage/Preferences/PreferenceKey.md:1:3-1:20
1 + # ``PreferenceKey``
2 |
3 | ## Topics
warning: Missing 'Image' child directive
The 'Chapter' directive must have exactly one 'Image' child directive
  --> Essentials/Introducing OpenSwiftUI.tutorial:8:5-12:6
6  |     }
7  |
8  +     @Chapter(name: "OpenSwiftUI Essentials") {
9  +         Learn how to use OpenSwiftUI to compose rich views out of simple ones,
10 +         set up data flow, and build the navigation while watching it unfold in
11 +         Xcode’s preview.
12 +     }
13 | }
warning: Missing required 'TutorialReference' child directive
The 'Chapter' directive requires at least one 'TutorialReference' child directive
  --> Essentials/Introducing OpenSwiftUI.tutorial:8:5-12:6
6  |     }
7  |
8  +     @Chapter(name: "OpenSwiftUI Essentials") {
9  +         Learn how to use OpenSwiftUI to compose rich views out of simple ones,
10 +         set up data flow, and build the navigation while watching it unfold in
11 +         Xcode’s preview.
12 +     }
13 | }
warning: No symbol matched 'OpenURLAction'. Can't resolve 'OpenURLAction'.
 --> EventHandling/SystemEvents/OpenURLAction.md:1:3-1:20
1 + # ``OpenURLAction``
2 |
3 | ## Topics
warning: No symbol matched 'AlignmentID'. Can't resolve 'AlignmentID'.
 --> Layout/LayoutAdjustments/Alignment/AlignmentID.md:1:3-1:18
1 + # ``AlignmentID``
2 |
3 | ## Topics
warning: No symbol matched 'HorizontalAlignment'. Can't resolve 'HorizontalAlignment'.
 --> Layout/LayoutAdjustments/Alignment/HorizontalAlignment.md:1:3-1:26
1 + # ``HorizontalAlignment``
2 |
3 | ## Topics
warning: No symbol matched 'VerticalAlignment'. Can't resolve 'VerticalAlignment'.
 --> Layout/LayoutAdjustments/Alignment/VerticalAlignment.md:1:3-1:24
1 + # ``VerticalAlignment``
2 |
3 | ## Topics
warning: No symbol matched 'ViewDimensions'. Can't resolve 'ViewDimensions'.
 --> Layout/LayoutAdjustments/Alignment/ViewDimensions.md:1:3-1:21
1 + # ``ViewDimensions``
2 |
3 | ## Topics
warning: No symbol matched 'Edge/Set'. Can't resolve 'Edge'.
 --> Layout/LayoutAdjustments/Edge/Edge.Set.md:1:3-1:15
1 + # ``Edge/Set``
2 |
3 | ## Topics
warning: No symbol matched 'Edge'. Can't resolve 'Edge'.
 --> Layout/LayoutAdjustments/Edge/Edge.md:1:3-1:11
1 + # ``Edge``
2 |
3 | ## Topics
warning: No symbol matched 'EdgeInsets'. Can't resolve 'EdgeInsets'.
 --> Layout/LayoutAdjustments/Edge/EdgeInsets.md:1:3-1:17
1 + # ``EdgeInsets``
2 |
3 | ## Topics
warning: No symbol matched 'HorizontalEdge'. Can't resolve 'HorizontalEdge'.
 --> Layout/LayoutAdjustments/Edge/HorizontalEdge.md:1:3-1:21
1 + # ``HorizontalEdge``
2 |
3 | ## Topics
warning: No symbol matched 'VerticalEdge'. Can't resolve 'VerticalEdge'.
 --> Layout/LayoutAdjustments/Edge/VerticalEdge.md:1:3-1:19
1 + # ``VerticalEdge``
2 |
3 | ## Topics
warning: No symbol matched 'OpenSwiftUI'. Can't resolve 'OpenSwiftUI'.
 --> OpenSwiftUI.md:1:3-1:18
1 + # ``OpenSwiftUI``
  |     ╰─suggestion: Replace 'OpenSwiftUI' with 'OpenSwiftUI'
2 |
3 | Declare the user interface and behavior for your app on every platform.
warning: No symbol matched 'Slider'. Can't resolve 'Slider'.
🖥️ rm -f /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/C3ADD938-A55A-47F3-B006-C75A0D961092/checkout/.docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41/linkable-entities.json
 --> Views/ControlsAndIndicators/Slider.md:1:3-1:13
1 + # ``Slider``
2 |
3 | ## Topicswarning: No TechnologyRoot to organize article-only documentation.
Article-only documentation needs a TechnologyRoot page (indicated by a `TechnologyRoot` directive within a `Metadata` directive) to define the root of the documentation hierarchy.Conversion complete! (0.05s)
Generated DocC archive at '/private/var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/C3ADD938-A55A-47F3-B006-C75A0D961092/checkout/.docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41'

[Kyle-Ye]

Running this locally (with our mechanism) reveals a few doc related warnings that might be relevant:

Thanks for the information. I'll run a local swift-docc to dig out what is happening under the hood.

The doc result on my local machine

1 + # OpenSwiftUI | ╰─suggestion: Replace 'OpenSwiftUI' with 'OpenSwiftUI'

Regardless of whether other warnings are effective or not, this warning seems to be a bug. LOL

[Kyle-Ye]

It looks to be a swift-docc-plugin for me.

Running swift-docc convert directly via Xcode or myself with the correct symbol-graph-dir would be fine.

# Expected layout
➜  symbol-graph tree -l                                                                                                                         
.
└── swift
    └── arm64-apple-ios-simulator
        ├── OpenSwiftUI.symbols.json
        ├── OpenSwiftUI@CoreFoundation.symbols.json
        ├── OpenSwiftUI@Swift.symbols.json
        └── OpenSwiftUI@UIKit.symbols.json

3 directories, 4 files

Removed the web related parameter and add --verbose at the end we can get the command swift-docc-plugin is using.

env DEVELOPER_DIR=/Applications/Xcode-15.3.0.app \
    xcrun swift package \
    --allow-writing-to-directory .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 \
    generate-documentation \
    --emit-digest \
    --disable-indexing \
    --output-path \
    .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 \
    --target OpenSwiftUI \
    --verbose

target symbol graph directory path: '/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI'
snippet extractor provided, attempting to generate snippet symbol graph
no snippet symbol graphs generated
docc archive output path: '/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/plugins/Swift-DocC/outputs/OpenSwiftUI.doccarchive'
docc invocation: '/Applications/Xcode-15.3.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc convert /Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/Sources/OpenSwiftUI/OpenSwiftUI.docc --emit-digest --output-path .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --fallback-display-name OpenSwiftUI --fallback-bundle-identifier OpenSwiftUI --additional-symbol-graph-dir /Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI'
Converting documentation...
warning: No symbol matched 'App'. Can't resolve 'App'.
 --> AppStructure/AppOrganization/App.md:1:3-1:10
1 + # ``App``
2 | 
3 | ## Topics
...

Checking the additional symbol-graph-dir "--additional-symbol-graph-dir /Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI'"

It is actually an empty directory.

tree -l /Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI           
/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI

0 directories, 0 files

[Kyle-Ye]

SPI is using .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0") which would be resolved to "1.3.0" in my case.

Change it to exact: "1.2.0" exact: "1.1.0" exact: "1.0.0" would give the same result.

I'm going to read the relevant swift-docc-plugin code to find out what is happening here.

[Kyle-Ye]

swift-docc-plugin is simply call the provided PackagePlugin API.

The actual implementation is in SwiftPM/PluginDelegate

// Run the symbol graph extractor on the target.
try symbolGraphExtractor.extractSymbolGraph(
    target: target,
    buildPlan: try buildSystem.buildPlan,
    outputRedirection: .collect,
    outputDirectory: outputDir,
-    verboseOutput: self.swiftTool.logLevel <= .info
+    verboseOutput: true
)

    public func extractSymbolGraph(
        ...
        // Run the extraction.
        let process = TSCBasic.Process(
            arguments: commandLine,
            outputRedirection: outputRedirection
        )
        try process.launch()
-        try process.waitUntilExit()
+        let result = try process.waitUntilExit()
+        print(result.description)
    }

(lldb) po commandLine
▿ 32 elements
  - 0 : "/Applications/Xcode-15.3.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift-symbolgraph-extract"
  - 1 : "-module-name"
  - 2 : "OpenSwiftUI"
  - 3 : "-target"
  - 4 : "arm64-apple-macosx10.15"
  - 5 : "-I"
  - 6 : "/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/debug"
  - 7 : "-sdk"
  - 8 : "/Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX14.4.sdk"
  - 9 : "-F"
  - 10 : "/Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Frameworks"
  - 11 : "-I"
  - 12 : "/Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/usr/lib"
  - 13 : "-L"
  - 14 : "/Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/usr/lib"
  - 15 : "-I"
  - 16 : "/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/debug/_OpenGraph.build"
  - 17 : "-I"
  - 18 : "/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/debug/TestingInternals.build"
  - 19 : "-I"
  - 20 : "/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/debug/COpenSwiftUI.build"
  - 21 : "-I"
  - 22 : "/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/Sources/CGTK"
  - 23 : "-module-cache-path"
  - 24 : "/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/debug/ModuleCache"
  - 25 : "-v"
  - 26 : "-minimum-access-level"
  - 27 : "public"
  - 28 : "-skip-inherited-docs"
  - 29 : "-emit-extension-block-symbols"
  - 30 : "-output-dir"
  - 31 : "/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI"

(lldb) po String(bytes: result.stderrOutput.get(), encoding: .utf8)
▿ Optional<String>
  - some : "<unknown>:0: error: missing required module \'AttributeGraph\'\nError: Failed to load the module \'OpenSwiftUI\'. Are you missing build dependencies or include/framework directories?\nSee the previous error messages for details. Aborting.\n"

Debugging the SwiftPM code gives me the exact error message here:

The swift-symbolgraph-extract is somehow missing the include/framework parameter for AttributeGraph.xcframework.

[Kyle-Ye]

I believe this is an upstream issue on SwiftPM. I can reproduce it using a simple DemoKit + any other normal binary target.

https://github.com/apple/swift-package-manager/issues/7580

[Kyle-Ye]

While waiting for a upstream response, I have 2 options here to my package to workaround:

1. The old 0.0.4 version's doc can build successfully reminds me that I can disable the binary AttributeGraph dependency and use OpenGraph when building the doc in SPI.

Use OG by default on Linux and AG by default in macOS after 0.0.4 If there is some env I can read or pass to the doc build process, I can add some logic here to workaround.

2. Or we can opt-out to use manually doc build script instead of SPI or other swift-docc-plugin based system like what we have done in swift-docc-symbolkit

[finestructure]

Interesting, thanks for following up! It sounds like there's nothing directly for us (SPI) to do here for the time being, or is there? Can I close the issue?

[Kyle-Ye]

It sounds like there's nothing directly for us (SPI) to do here for the time being, or is there?

Yes. As a SPI user who suffered the docc-plugin bug, I'd like to know is there any way we can opt-out to use swift-docc-plugin or is there any stable bool environment variable I can read from in my Package.swift when building docs? (eg. SWIFT_PACKAGE_INDEX_BUILD_DOC=1)

[finestructure]

We do indeed set two variables to 1 when building and generating docs:

• SPI_BUILD
• SPI_GENERATE_DOCS

[Kyle-Ye]

We do indeed set two variables to 1 when building and generating docs:

• SPI_BUILD
• SPI_GENERATE_DOCS

Got it. Thanks. I'll use SPI_GENERATE_DOCS to do the trick then.

[Kyle-Ye]

Disable AG binary and use OG to build the doc via SPI/swift-docc-plugin is still not working.

OPENGRAPH_ATTRIBUTEGRAPH=1 DEVELOPER_DIR=/Applications/Xcode-15.3.0.app xcrun swift package --allow-writing-to-directory .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 generate-documentation --emit-digest --disable-indexing --output-path .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --hosting-base-path openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --source-service github --source-service-base-url https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --checkout-path /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/C3ADD938-A55A-47F3-B006-C75A0D961092/checkout --target OpenSwiftUI
...
error: 'docc convert' invocation failed with a nonzero exit code: '5'
target symbol graph directory path: '/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI'
snippet extractor provided, attempting to generate snippet symbol graph
no snippet symbol graphs generated
docc archive output path: '/Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/plugins/Swift-DocC/outputs/OpenSwiftUI.doccarchive'
docc invocation: '/Applications/Xcode-15.3.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc convert /Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/Sources/OpenSwiftUI/OpenSwiftUI.docc --emit-digest --output-path .docs/openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --hosting-base-path openswiftuiproject/openswiftui/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --source-service github --source-service-base-url https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/663b6ac79cfb0f13c06511fb270ddb3334a09c41 --checkout-path /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/C3ADD938-A55A-47F3-B006-C75A0D961092/checkout --fallback-display-name OpenSwiftUI --fallback-bundle-identifier OpenSwiftUI --additional-symbol-graph-dir /Users/kyle/Developer/OpenSwiftUIProject/OpenSwiftUI/.build/arm64-apple-macosx/extracted-symbols/openswiftui/OpenSwiftUI'
Converting documentation...
error: 'docc convert' invocation failed with a nonzero exit code: '5'

Running the command directly and we'll get the following error message

[1]    32221 trace trap   convert  --emit-digest --output-path  --hosting-base-path  --source-service

I attached the launch parameter and set up swift-docc source code to debug it.

💥 There is another bug in release/5.10 and main of swift-docc.

(lldb) po url
file://<redacted>/OpenSwiftUI/Sources/OpenSwiftUI/OpenSwiftUI.docc/Layout/LayoutAdjustments/Alignment/AlignmentID.md
(lldb) po diagnosticRange.lowerBound.line
58
(lldb) po max(1, diagnosticRange.lowerBound.line-2)-1
55
(lldb) po sourceLines.count
7
(lldb) po diagnosticRange.upperBound.line
62
(lldb) po min(sourceLines.count, diagnosticRange.upperBound.line + 2)
7

cc @d-ronnqvist @arthurcro

I'll file a issue on swift-docc later with more detail and minimal reproducible package.

[Kyle-Ye]

1. Use OPENGRAPH_ATTRIBUTEGRAPH=0 when SPI_GENERATE_DOCS=1 to by-pass swift-docc-plugin issue
2. Use --ide-console-output to by-pass swift-docc issue

Then I can finally build out the doc via SPI again. 🎉

But actually compared to add SPI_GENERATE_DOCS check code on OpenSwiftUI and OpenGraph's Package.swift, I'd like to solely update my .spi.yml to fix the issue.

// Package.swift on OpenSwiftUI
#if os(macOS)
- let attributeGraphCondition = envEnable("OPENGRAPH_ATTRIBUTEGRAPH", default: true)
+ let attributeGraphCondition = envEnable("OPENGRAPH_ATTRIBUTEGRAPH", default: !envEnable("SPI_GENERATE_DOCS", default: false)) // By-pass apple/swift-docc-plugin#80
#else
let attributeGraphCondition = envEnable("OPENGRAPH_ATTRIBUTEGRAPH")
#endif

// Package.swift on OpenGraph
#if os(macOS)
- let attributeGraphCondition = envEnable("OPENGRAPH_ATTRIBUTEGRAPH", default: true)
+ let attributeGraphCondition = envEnable("OPENGRAPH_ATTRIBUTEGRAPH", default: !envEnable("SPI_GENERATE_DOCS", default: false)) // By-pass apple/swift-docc-plugin#80
#else
let attributeGraphCondition = envEnable("OPENGRAPH_ATTRIBUTEGRAPH")
#endif

The current API only have customDocumentationParameters. And I suggest we add a new customDocumentationEnvironment property here, what do you think of it? @finestructure

// .spi.yml on OpenSwiftUI
version: 1
builder:
  configs:
    - documentation_targets: [OpenSwiftUI]
+    - customDocumentationEnvironment: ["OPENGRAPH_ATTRIBUTEGRAPH=0"] # By-pass apple/swift-docc-plugin#80
+    - customDocumentationParameters: ["--ide-console-output"] # By-pass apple/swift-docc#729

[finestructure]

I'd like to avoid extending the SPI manifest and the builder unless we absolutely have to. Since there's a possible upstream fix it would be better to solve the issue there, because once we add this we can't really remove it again. Whereas if you add a workaround in your .spi.yml you can revert it once the fix is in place.

Does that make sense?

[Kyle-Ye]

Got it. I'll wait for upstream fix or use SPI_GENERATE_DOCS in my Package.swift.

I'd like to avoid extending the SPI manifest and the builder unless we absolutely have to.

Yeah. Make sense and I can understand your standpoint as the maintainer of SPI manifest. (Although I thought it would be usable to add "customDocumentationEnvironment" since we already have "customDocumentationParameters" in manifest at the first place.)

[finestructure]

Is it ok to close this issue while we wait for an upstream fix, @Kyle-Ye ?

[Kyle-Ye]

Update: The apple/swift-docc#729 is fixed on release/6.0 and main. The bug on swift-docc-plugin have no update yet.

[Kyle-Ye]

Update:

The remaining bug is tracked on swiftlang/swift-package-manager#7580 instead of swift-docc-plugin.

My PR is ready. Waiting for a review.