search

fireblade-engine / ecs

A dependency free, lightweight, fast Entity-Component System (ECS) implementation in Swift
MIT License
110 stars 11 forks source link

DocC Documentation #76

Open ctreffs opened 4 days ago

ctreffs commented 4 days ago

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/swiftdoccplugin

Describe 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.

heckj commented 3 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?)

ctreffs commented 3 days ago

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 😄

heckj commented 3 days ago

I'm away from my laptop this week, but once back I'll get a quick PR set up to host the docs.