docs: only use one target for SPI documentation #374
Conversation
Remove additional documentation targets which are platform flavours. @cbaker6 Corey, I believe the intention here was to create four different doc sets here, one per platform. Unfortunately, that's not how our DocC generation (or DocC generation in general?) works. The docset for all four targets is called `parseswift` and they end up simply overwriting each other in sequence. So currently you're hosting the last one, for watchOS. It's an outstanding item on my todo list to bring up with the DocC working group how multi-platform docsets are supposed to be generated and hosted side-by-side. I don't think there's anything we can do at the moment to address this :( I'm not sure to what extent you have control over creating entirely separate doc targets which would allow you to ship separate sets per platform if they're materially different. If that's the case, would you like to open a discussion over in https://github.com/SwiftPackageIndex/SwiftPackageIndex-Server/discussions to see if this can be worked around somehow? I can go into more detail how the process works from our end which might allow experimentation on your end. If there is one canonical or best suited set of docs to generate, it's best to only specify that for now!
Thanks for opening this pull request!
|
Codecov Report
@@ Coverage Diff @@
## main #374 +/- ##
==========================================
- Coverage 89.12% 89.11% -0.02%
==========================================
Files 140 140
Lines 13546 13546
==========================================
- Hits 12073 12071 -2
- Misses 1473 1475 +2
Continue to review full report at Codecov.
|
Hi Sven, thanks for the fix. I was testing this based on the SPI blog with the intent to see what happens.
The docs for Pare-Swift are essentially the same, so we can go with one target. |
cbaker6
changed the title
New Pull Request Checklist
Issue Description
Remove additional documentation targets which are platform flavours.
@cbaker6 Corey, I believe the intention here was to create four different doc sets here, one per platform. Unfortunately, that's not how our DocC generation (or DocC generation in general?) works.
The docset for all four targets is called
parseswiftand they end up simply overwriting each other in sequence. So currently you're hosting the last one, for watchOS. It's an outstanding item on my todo list to bring up with the DocC working group how multi-platform docsets are supposed to be generated and hosted side-by-side. I don't think there's anything we can do at the moment to address this :(I'm not sure to what extent you have control over creating entirely separate doc targets which would allow you to ship separate sets per platform if they're materially different. If that's the case, would you like to open a discussion over in https://github.com/SwiftPackageIndex/SwiftPackageIndex-Server/discussions to see if this can be worked around somehow? I can go into more detail how the process works from our end which might allow experimentation on your end.
If there is one canonical or best suited set of docs to generate, it's best to only specify that for now!
Related issue: #n/a
Approach
TODOs before merging