Over at SPI, we're hosting DocC docs for Swift packages if authors opt-in with a config file .spi.yml
in their repository. Here's an example of such an opt-in:
version: 1
builder:
configs:
- platform: macos
scheme: ChimeKit
- documentation_targets: [ChimeExtensionInterface, ChimeLSPAdapter]
Package authors configure a list of targets they'd like us to generate docs for. This has worked fine with all targets displaying docs when we generated the docs with Swift 5.6.
One particular issue we had to work around was that package plugin generate-documentation
only has a single target flag --target
. In order to generate docs for all targets, we loop over them. There's a slight hitch in that DocC clobbers the output directory when doing this. I.e. it doesn't just add file from subsequent targets but instead nukes the output directory completely on each run.
We worked around this by copying the output away between runs. I've always had the nagging feeling that this sequential processing will come to haunt us but for all the 5.6-generated docs we've seen this has been working fine.
This changed with 5.7 and its sidebar.
It seems that the file index/index.json
contains information specific to a target's sidebar and all targets write to this same file. So what we're observing is that in terms of a working sidebar "last target wins".
Our hack has finally caught up with us, because of course it would
Best I can tell, there's no way to generate docs for a list of targets with a consolidated index.json
, or is there?
It feels like our only options are to get a --targets
flag into the DocC plugin or somehow merge index.json
- if that's even possible, at least as workaround (that surely won't cause problems, nono) until there's a better solution.
Is our observation that index/index.json
contention is the problem correct? Is there any way for us to recover multi-target sidebars with 5.7?