After upgrading our toolchain to Xcode 16, we noticed that the "load time" of the DocC API reference website has significantly increased. When I open our daily build API reference website, it takes more than 20 seconds to load the landing page. While it only takes less than 1 second for our released website built with Xcode 15.
Upon examining the performance, I noticed that the index.json file takes around 20 seconds to load, despite its relatively small file size.
First, I tried to figure out where the issue came from. After bisecting, I found that…
we didn't make any change to the DocC archiving script
after upgrading to Xcode 16, the slow load time problem occurred
the DocC web hosted files also bloated in size, increased by 10+MB
Second, I tried the latest toolchain in Xcode 16.1. I built the documentation and started a local server to see if the problem persists - it does. See the attached screenshot. It took 22 seconds to load the index.json.
Third, I tried to find some clue from the latest documentation on DocC. I had a few interesting findings:
In the past, we used to use the xcodebuild docbuild command to build the DocC archive, then use $(xcrun --find docc) process-archive to convert the archive into web hosting files with a base path.
Now, it seems the latest recommended equivalent approach becomes docc convert command described here. I gave it a try and while the web hosting files are successfully generated, they still suffer from the slow load time.
There is another new thing called the Swift-DocC plugin, which I also gave a try. It seems promising as its documentation mentioned:
By default, the Swift-DocC plugin will generate an index of content that is useful for IDE’s, like Xcode, to render a navigator of all included documentation in the archive. Since this index isn’t relevant when hosting online, you can pass the --disable-indexing flag when generating documentation thats intended for an online host.
However, it fails to build for me with some error related to platform API availability. Our package targets iOS, Mac Catalyst, and VisionOS, and I cannot seem to find a way to specify "only building doc for supported platforms" in the DocC subcommands.
Is this slow load time a known issue for DocC in Xcode 16?
Is there a solution without using the Swift-DocC plugin, and simply use the original xcodebuild docbuild approach?
Is there a flag or parameter like the Xcode build settings "DOCC_HOSTING_BASE_PATH" that we can specify, to skip indexing for web hosting with --disable-indexing flag?
I see some discussion on "EXTRA_DOCC_FLAGS" here, but want to double check that it is a viable solution before I kick off another build.
Yes, this sounds like #894 to me, which was recently fixed.
[Y]ou can verify this in one of two ways:
download the latest Swift toolchain and try to reproduce
clone the latest swift-docc-render-artifact and add an additional environment variable to your existing command to build the docs as follows: DOCC_HTML_DIR=/path/to/swift-docc-render-artifact/dist
As @j-f1 mentioned, this is most likely a renderer regression that has since been fixed. It would be most noticeable for any page with a large number of links.
It technically shouldn't impact the time it takes to load the index JSON file, but maybe there was something that makes it seem that way.
The mentioned steps to either use the latest Swift toolchain or the latest renderer should be enough to make sure that this is resolved with the latest tools. If not, please feel free to file a GitHub issue on Swift-DocC-Render with as many details as possible.
Thank you. We tested with the latest artifact and the load time returns to normal.
Can you please include an Xcode release note item when the fix goes it, so we can remove the temporary workaround. Thanks!