Open ctreffs opened 4 days ago
I'd be more than happy to set you up with this. Worth noting that once enabled, with an .spi.yml
file, you'll get hosted documentation through the Swift Package Index if you'd like to take advantage of that. Is there a place you'd explicitly like to host docs? (e.g. GitHub pages for this repository?)
Documentation on Swift Package Index would be great. Other than that I don't really have a strong opinion where documentation is hosted, as long as it's easily available to users. If we'd only provide documentation on SPI that would be fine by me, but are there drawbacks to how current documentation would be (e.g. only generated when there is a new tag available)? The generation part of DocC is easy enough, adjusting CI as well, but regarding hosting and publishing I'm currently a little lost. So if you want I could tackle the first bit (Plugin & CI integration) and you'd extend it with hosting & publishing? Sounds like a plan @heckj?
PS: I've read up on this here https://swiftpackageindex.com/SwiftPackageIndex/SPIManifest/1.7.0/documentation/spimanifest/commonusecases - sounds great!
Your package manifest Package.swift does not need to include the DocC plugin in order for us to host your DocC documentation. We will automatically inject it when building your documentation if we don’t detect the plugin in your manifest.
So we'd just add .spi.yml
and the rest would be done for us? Sounds even better 😄
I'm away from my laptop this week, but once back I'll get a quick PR set up to host the docs.
Feature request
We currently do have a CI workflow
documentation.yml
in place (that's broken). It uses an old and outdated way to generate documentation that is published to this repositories Wiki pages. That's neither nice nor good to maintain. DocC is the de-facto standard for Swift project nowadays. We should migrate to DocC to generate documentation for this project. A good starting point is: https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccpluginDescribe the solution you'd like
Use DocC to generate documentation.
Describe alternatives you've considered
Manual generation steps are tedious to maintain and don't offer as many proven features as DocC does.