Doc sidebar not showing correct module in Swift 6.1 generated docs

[finestructure]

This page should show the StructuredQueriesCore in the sidebar:

https://swiftpackageindex.com/pointfreeco/swift-structured-queries/0.1.1/documentation/structuredqueriescore

This is what it looked like when generated with Swift 6.0 for the previous version of the package, 0.1.0:

[finestructure]

This also affects other packages like https://swiftpackageindex.com/ph1ps/swift-semantic-version/main/documentation/semanticversionmacro, so it's likely a universal problem with Swift 6.1.

[d-ronnqvist]

There are two modules in that index and "StructuredQueries" appear to be the first hierarchy:

$ jq '.interfaceLanguages[][].path' index.json

"/documentation/structuredqueries"
"/documentation/structuredqueriescore"

How are you creating that index?

[finestructure]

We are generating docs for each target individually and then merging the index.json files together. I'm attaching the one for 0.1.0 (from a Swift 6.0 doc build) and 0.1.1 (from the Swift 6.1 doc build) below.

The relevant code is

import Foundation

import DocUploadBundle


extension DocArchive {
    struct Index: Codable, Equatable {
        var interfaceLanguages: Language
        var schemaVersion: Version

        struct Language: Codable, Equatable {
            var swift: [Child]

            struct Child: Codable, Equatable {
                var children: [Child]?
                var path: String?
                var title: String
                var type: String
            }
        }

        struct Version: Codable, Equatable {
            var major: Int
            var minor: Int
            var patch: Int
        }
    }
}


extension DocArchive.Index {
    init?(path: String) {
        guard let data = Current.fileManager.contents(atPath: path),
              let index = try? JSONDecoder().decode(DocArchive.Index.self, from: data)
        else { return nil }
        self = index
    }

    func save(to path: String) -> Bool {
        guard let data = try? JSONEncoder().encode(self) else { return false }
        return Current.fileManager.createFile(atPath: path, contents: data)
    }
}


extension DocArchive.Index {
    func merging(with index: Self) -> Self {
        .init(
            interfaceLanguages: .init(swift: interfaceLanguages.swift + index.interfaceLanguages.swift),
            schemaVersion: schemaVersion
        )
    }

    static func mergeIndex(atPath path1: String, with path2: String) {
        switch (Current.fileManager.fileExists(atPath: path1),
                Current.fileManager.fileExists(atPath: path2)) {
            case (true, true):   // both files exist -> merge
                if let index = DocArchive.Index(path: path1),
                   let newIndex = DocArchive.Index(path: path2) {
                    let merged = index.merging(with: newIndex)
                    if merged.save(to: path1) {
                        Logger.log("Successfully merged into \(path1)")
                    } else {
                        Logger.log("Failed to merge into \(path1)")
                    }
                } else {
                    Logger.log("Could not merge \(path2)")
                }
            case (false, true):  // only new file exists -> copy it over
                let data = Current.fileManager.contents(atPath: path2)
                if !Current.fileManager.createFile(atPath: path1, contents: data) {
                    Logger.log("Failed to save file to \(path1)")
                }
            case (true, false),  // only staging file exists -> do nothing
                (false, false):  // neither file exists -> do nothing
                break
        }
    }
}

index-swift-6.0.json.zip
index-swift-6.1.json.zip

[d-ronnqvist]

At a glance it looks like swiftlang/swift-docc-render#929 would fix this problem but I don't think that's in the 6.1 release. I wonder if swiftlang/swift-docc-render#916 in combination with swiftlang/swift-docc-render#904 is what caused this regression.

[finestructure]

Thanks a lot for taking a look, David. I think we need to roll back doc generation to 6.0 in that case as I don't think I can deploy such a change in a hurry.

[finestructure]

Related builder change: https://gitlab.com/finestructure/swiftpackageindex-builder/-/merge_requests/336

[finestructure]

Rolling back to Swift 6.0 doc gen has fixed the issue: