We've added a new feature to the Swift Package Index which hopefully make your lives as package developers easier: when you opt-in your package, we'll be auto-generating your DocC compatible documentation and host it on your package page in the Swift Package Index. We'll also be auto-updating it as part of our normal build operations.
This is great news- congratulations on the launch! The simplified publishing offered by the Swift Package Index here is a game changer for folks interested in publishing Swift-DocC documentation.
Looking forward to seeing how this project evolves moving forward. Already on my list is looking into how the Swift-DocC Plugin can better serve use cases like this. I think that, ideally, folks interested in using the plugin just for publication integrations like this one shouldn't need to explicitly adopt it as a dependency of their package. Some flavor of default SwiftPM command plugins could be really helpful.
Thank you for all of your work here! And congratulations again.
Thanks so much for your kind words, Ethan, and everyone in and around the DocC team who've built the underlying tools and who've helped us put this together!
@fabianfett actually mentioned that it might be possible for us to avoid the plug-in dependency for authors entirely and we'll definitely be looking into whether we can make this work with docc directly!
Congratulations @finestructure! When finding and publishing documentation is this easy, there's no reason not to write great docs! This is huge step towards better documentation for the whole Swift community.
I'd be curious to hear your thoughts around documentation search—this is another area I think DocC could improve.
the goal of the swiftinit.org project was to serve ecosystem docs essentially like the feature the SPI just rolled out, but in a more integrated fashion. i had been working on it day-and-night for approximately 6 months, but the project hit major implementation snags several weeks ago when i tried to add support for versioning and documentation history, as this is a surprisingly deep and convoluted problem when it interacts with extensions on cross-package types. when Sven posted his announcement, i felt that my work had been made obsolete, which is why i did not welcome his announcement in the way that i should have.
Sorry to hear that you felt like your work was made obsolete, @taylorswift ! Of course that wasn't our intention and we weren't aware of your intentions for the site. When we spoke at the Documentation WG meeting our plans were already well formed and it just so happened that the gap between meetings was large enough for us to complete the first part of this feature.
I believe there's merit in being able to link between packages but our goal wasn't/isn't to solve that at the package index level but rather adopt whatever linking mechanism DocC itself may support at some point.
I also think that while cross-linking might be interesting for some packages by specific authors, I suspect the vast majority of packages will at most want to link to standard library documentation and so are naturally siloed.
An easy way to see this is by looking at the long tail of packages that import little to no dependencies.
i understand. to be honest if i were you i also would have forged ahead. i had been so caught up in the stress of first-to-publish it didn’t even occur to me that you might have felt similarly pressured.
correct. this was the sinking realization that i never really confronted until today, that the silo-ing shortcut ended up being the winning strategy, if only because it makes the problem of serving package documentation tractable.
right, in hindsight i was spending all my time solving a problem that doesn’t really exist in the real world, probably because i maintain a ‘deep’ stack of dependencies that is not representative of how a majority of swift developers work. you had a better understanding of the market than i did.
i’m not really one to cry about getting outmaneuvered, so i suppose all i can do is congratulate you on a project well-planned. i certainly learned a lot from this experience…
Huge congratulations on launching @daveverwer@finestructure! The ability to find packages and quickly jump to their documentation is really delightful.
+1 on Ethan's point about not requiring packages to explicitly include the Swift-DocC plugin—this would reduce friction in publishing documentation even more. And as discussed with Dave and Sven, integrating the information declared by the .spi.yml file (i.e., what targets to build documentation for) into the package manifest directly would be a natural step forward. Maybe there are some sensible defaults we could use here, e.g., always publish documentation for products, but not tests.
Just some food for thought, Swift-DocC has an --emit-digest flag that produces an index of the documentation content available in a DocC archive. It would be neat to use that info to allow Swift Package Index's search field to also search for symbols within packages.
Big congratulations and I'm very excited to see more documentation!
For example, I use a custom DocC-render and host the docs on GitHub Pages. Can I also get that "Documentation" button, and have it point to my existing URL?
That said, I also don't mind if SPI wants to render and host its own version of the docs. I don't see a downside to enabling it, especially if there might be better support for versioning or other benefits in the future. I don't use the plugin, though, so if I could notify SPI about the presence of DocC-compatible documentation solely through the YAML file, that would be nice.