Collision merging image references when librairies in one swift package have files with same name in their own folders

[pylapp]

Description

The project is a Swift package exposing several librairies.
Each library has its own DocC markup file and a resources folder with images to add in documentation.
These images appear in the Xcode documentation viewer and also in the built documentation from Xcode (i.e. dedicated Xcode window).

However, when this documentation is built for a static web site, with the combined target experimental feature gathering all documentation of all librairies for my Swift package, I face the following issues: there are collision of files if several files with same name exist even if different locations

The command:

swift package \
    --allow-writing-to-directory "$DOCUMENTATION_HTML_LOCATION" \
    generate-documentation \
    --enable-experimental-combined-documentation \
    --target OUDS \
    --target OUDSModules \
    --target OUDSComponents \
    --target OUDSThemesOrange \
    --target OUDSThemesOrangeInverse \
    --target OUDSThemesOrangeBusinessTools \
    --target OUDSThemesSosh \
    --target OUDSThemesWireframe \
    --target OUDSTokensComponent \
    --target OUDSTokensSemantic \
    --target OUDSTokensRaw \
    --target OUDSFoundations \
    --output-path "$DOCUMENTATION_HTML_LOCATION" \
    --transform-for-static-hosting \
    --warnings-as-errors \
    --symbol-graph-minimum-access-level public

The issue

For example, I have two modules named OUDSThemeOrange and OUDSThemesOrangeBusinessTools with in their markup files the code:

@Metadata {
    @PageImage(purpose: card, source: "ic_theme")
    @PageImage(purpose: icon, source: "ic_theme")
}

These two modules have a Resources folder and inside a _ subfolder with inside the ic_theme.png file.

The error

Error: Collision merging image references. Reference 'ic_theme.png' exists in more than one input archive.

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

Maybe have collision of files managed

Actual behavior

If collision the geenration of the doc failed

Steps To Reproduce

• macOS Sequoia 15.6
• Xcode 16.2

Swift-DocC Version Information

I do not know of to get it

Swift Compiler Version Information

swift-driver version: 1.120.5 Apple Swift version 6.1 (swiftlang-6.1.0.110.21 clang-1700.0.13.3)
Target: x86_64-apple-macosx15.0

[d-ronnqvist]

What's the content of the "image" directory inside "OUDSThemeOrange.doccarchive" and "OUDSThemesOrangeBusinessTools.doccarchive"? It looks like both targets are possibly specify the same documentation identifier which isn't allowed.

[pylapp]

In fact these two librairies must be isolated. The Swift packahe provides, in few words, themes for applications, and these two librairies are themes so they are not supposed to depend each other.

However their documentation are a bit similar and uses sometimes the sames icons, here the ic_theme.png. Because they are isolated they embed their versions of the icons in the Resources folders. This folder is supposed also to contain illustrations and other images for the theme.

I am not sure to understand your question about the doccarchives. I shared them in attachments if needed.

If i look in the content of the images folder in each doccarchive I have for each folder one file:

• ouds-ios.OUDSThemesOrangeBusinessTools/ic_theme.png
• ouds-ios.OUDSThemesOrange/ic_theme.png

Mentioned doccarchives.zip