Missing DocC sidebar content #2036
Comments
|
I just looked at a few other packages, and they don't seem to have this issue. Something is special about mine, but I don't understand what yet... |
|
Do you have an example of a package we're generating with 5.7 docs that doesn't have this issue? It'll save me a little time finding one! |
|
Thanks, Matt! We'll look into this. |
|
Ok and here's another one of mine with no sidebar at all! Obviously this is my issue somehow... https://swiftpackageindex.com/ChimeHQ/ConcurrencyPlus/0.3.1/documentation/concurrencyplus |
|
This one hasn't been built with 5.7 - that's why it doesn't have one: https://swiftpackageindex.com/ChimeHQ/ConcurrencyPlus/builds You can see that the 5.7 builds are still pending. It should update once those go through. |
|
ChimeKit has data for the second target: https://swiftpackageindex.com/ChimeHQ/ChimeKit/main/documentation/chimelspadapter Is there perhaps some difference between the two? I'll check the detailed builds logs. |
|
It looks like that's the only target that had docs generated: https://swiftpackageindex.com/builds/43CE99B2-3FB2-468D-97A2-0E3607B21C9C |
|
Ah no, the first target is being processed but there are some warnings which perhaps cause issues? |
|
Hmm, so yes, ChimeKit has multiple targets. But I can see the documentation for the one I'm talking about right here: https://swiftpackageindex.com/ChimeHQ/ChimeKit/main/documentation/chimeextensioninterface And as for ConcurrencyPlus, why would the version of Swift influence the docs web configuration? |
Because we're now building docs with 5.7 but we've not deleted 5.6 generated docs. So only once the 5.7 job goes through will it update the docs to the sidebar version (which is the 5.7 version). |
|
To clarify: we're only generating docs for one platform/Swift version combination out of the 24 combos we're building. Before 5.7 that was macos-spm/5.6 (or ios/5.6 if so configured by the author). This is now macos-spm/5.7 (or ios/5.7). |
Yes, I know about those. Some I just resolved some, but I had assumed since they were warnings and Xcode was doing what I wanted, the web version would as well. I also didn't realize that the sidebar was a Swift 5.7 thing. Very interesting! While I have no idea what's special about my docs, I don't yet have any reason to blame SPI. I'm going to try to get the web version working locally and then I'll blame you 😉 |
|
Ok, so local version has sidebar content... |
|
So I was just poking around at the site, and I noticed three resources that are unable to load: Could this be related? I do seem to have these files locally. |
|
Mmmm, all three files exist in S3: Are you getting any 404s in the browser console? I'm not, FWIW. Can you reproduce the broken sidebar if you remove the files locally? |
|
Also, and this shouldn't make a difference but 🤷♂️, are you getting the same result if you build and preview the docs via SPM (like we do)? For this to work, you'll need to add the docc plugin to your package's dependencies temporarily: |
|
Ok, I think the problems loading the files is user error on my part. I can load them if I just put the URL in - it seems Safari's resource inspector was just unhappy... |
|
Just tried out the SPM-based preview. Sidebar has expected content. |
|
If you could try this, please? (I edited the message after posting, sorry!)
I'll try running this in the debugger locally tomorrow but it'd be really helpful to know which file exactly is not being proxied. It's going to be super hard to know what to look for otherwise 😅 One other (unlikely) thing that could be happening is that Cloudflare "cached" something as unavailable and it'll just take a while to be available on retry. I believe the TTL is 4h, so this might already be ruled out depending on when you first observed this. |
|
I thought I might have found something. Was noticing resources that differ by case. But, it looks like a package whose sidebar works right also has the same thing.
|
|
I suspected caching too. I've been looking more closely at the code, and I can only see two things that are special about this package: it has multiple documentation targets and it can only be built with Swift 5.7. |
|
Let's try this: I've attached a zip with the content of the |
|
This should be the equivalent of what we're doing builder-side: |
|
I've been starting up a local webserver in the exported directory, and then navigating to the pages in safari. When I do this with my exported copy, it works. I'm not able to use the same technique to load the copy you sent me. I am sometimes (but no always) getting errors in the server console: These never happen with my locally-generated copy. |
|
Oh wait, I think understand what's wrong... |
|
Yes, has to be rooted with the same path. Ok, "success"! I've loaded your copy and it indeed is missing a sidebar! |
|
From your copy, some missing files: I moved my local copies in, thinking for sure that would fix it, but it did not! |
|
Not sure these are relevant - ParseSwift doesn't have them but shows a sidebar:
|
|
I have the suspicion that this is happening because of a work-around we've had to employ to make multi-target docs work. As far as I know, there's no way to process all targets at once. So what we're doing is looping over configured documentation targets and generating docs for each in turn. The problem is that DocC clobbers the output directory on each run. To work around that we copy the output to a staging directory for upload after each target. My suspicion is that there's an aggregate file for the sidebar and what we're seeing is "last file wins". That's why it works for the second target This would also explain why it works fine for ParseSwift - it has only one target. @icanzilb is the DocC expert - could this be what's happening? Do you know which files drive the sidebar? |
|
It's the I get
That seems to confirm that we're clobbering the first target with the second target's I'm not sure how we're going to generate multi-target docs unless there's a built-in way to pass in multiple targets to the generator. |
|
I'll write something up for the Swift forums to ask for help. |
|
Ok, I've done something horrible - and it works 😬 The
They're easily mergeable: struct Index: Codable {
var interfaceLanguages: Language
var schemaVersion: Version
struct Language: Codable {
var swift: [Child]
struct Child: Codable {
var children: [Child]?
var path: String?
var title: String
var type: String
}
}
struct Version: Codable {
var major: Int
var minor: Int
var patch: Int
}
}
let data1 = try Data(contentsOf: URL(fileURLWithPath: file1))
let index1 = try JSONDecoder().decode(Index.self, from: data1)
let data2 = try Data(contentsOf: URL(fileURLWithPath: file2))
let index2 = try JSONDecoder().decode(Index.self, from: data2)
let merged = Index.init(
interfaceLanguages: .init(swift: index1.interfaceLanguages.swift + index2.interfaceLanguages.swift),
schemaVersion: index1.schemaVersion
)
let mergedData = try JSONEncoder().encode(merged)
try mergedData.write(to: URL(fileURLWithPath: mergedFile))We could just do that for now until there's a better solution. It's hacky but it's not like we could break it any further. I've uploaded the |
|
Wow, fantastic work. Is your plan to leave this in place until you find a more official solution? |
|
I think unless I hear otherwise from the docc folks I'll add this workaround to the builder for now, yes. Note that the current docs are manually patched for that repo and will break again once you push a change. I'll update this issue once I've added the workaround! |
|
@finestructure the sidebar release is after my time, I know how I'd build it myself but no idea how it's actually working in the release |
|
No worries, thanks for the info @icanzilb ! |
|
Just to update this issue: DocC's sidebar currently does not support multiple targets. Our workaround above should be ok for now and there's currently not really any other way to achieve this. |
|
Fixed here: https://gitlab.com/finestructure/swiftpackageindex-builder/-/merge_requests/153
|
|
This is deployed and it's fixed last night's re-run with the broken sidebar. (NB: make sure to reset your local browser cache to refresh this properly. Mine was showing a broken sidebar initially.) |
|
Thank you so, so much! Really amazing how quickly you got this understood and fixed. |
|
I'm seeing this with RediStack https://swiftpackageindex.com/Mordil/RediStack/master/documentation/redistack Is there something in particular that has to be done to make the package be built with 5.7, or is it just a batch job y'all limit & control which packages goes into which batch? |
|
I see you’ve pushed to (The reason you see 5.7 generated docs at all is because we processed the package when catching up with 5.7 builds but that pass must have run without the fix for this.) |
|
Oh, got it. I don’t know why that didn’t occur to me. Thanks Sven! |
I've been working on my docs for https://swiftpackageindex.com/ChimeHQ/ChimeKit. I was surprised to see the sidebar was empty, showing just the target name and "No data available."
In Xcode's doc viewer, I see this:
I'm pretty new to docc, so I could definitely be doing something wrong. I also cannot quite figure out how to generate local static web content, but I'm working on it...
The text was updated successfully, but these errors were encountered: