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.
Yes, we're currently linking to the docs generated from the default branch and will link to individual releases soon. (See "Next Steps" in the blog post.)
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!
Congrats! Looking forward to updating more of our projects
I'm not quite sure how swiftinit.org is intended to be used, but SPI serving documentation for its existing index of many non-Apple packages seems to mostly serve a different purpose.
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 believe the DocC version coming with Swift 5.7 will mostly take care of that by adding a sidebar with a search field to the documentation viewer.
There's a larger question around how that might integrate with the rest of the site but at least initially that should help navigate the docs for a given package.
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.
One of the next things we'll do is allow authors to configure the "Documentation" button to link to their own docs instead of having us generate and host it.
I'm not sure how uncomfortable people feel with this.
Which url is canonical?
Which url should I use when I want to link to the documentation?
Which url contains the documentation of the latest stable release? Or is it the documentation of the main branch? There's no versioning visible anywhere.
How do search engines such as Google deal with such duplicated content?
I, personally, am confused. I know you all want the best, but do you have an opinion about those concerns?
EDIT - this is the same with TCA (and maybe others):
The developer Documentation site Apple Developer Documentation is not about swift-docc's doc itself, but some examples of docc usage.
For an example of Swift-DocC in action, check out developer.apple.com. Much of Apple's developer documentation, from Reference documentation to Tutorials, is built using Swift-DocC.
The latest documentation for the Swift-DocC project is available on Swift.org.