Building versioned documentation for previously published versions

[dan-stytch]

Hi there — firstly thanks so much for building out support for versioned documentation, it's already a huge win!

I wanted to pose an idea for discussion: It seems versioned documentation will only be built for new tags published after versioned documentation was enabled and I'm curious if there is a way (or if there is interest in creating one) to do one-off builds for the older/previously existing versions of a library, such that the entire documentation history could be hosted together. It would be great to have docs for every version centrally available on SwiftPackageIndex.

I'll leave it there for now simply to kickstart discussion. Thanks again!

[daveverwer]

Hi Dan, and thanks for starting the discussion

Since we hooked the documentation generation phase onto the end of the compatibility building phase (since both of those tasks need to build), this is a little tricky. We have a very robust system for making sure we build every package when a new tag appears or when the default branch moves forward, but it was never built to go back in time.

That's not to say it's not possible, but it would certainly not be a trivial change to make.

The other slight issue is how new DocC is. Yes, documentation comments have been around for a while, but DocC itself has only been around for a short while. Even if we had a mechanism for going back, we'd only be able to compile docs for packages where the old version would build with Swift 5.6 and the DocC plugin.

A good first step for us to decide this would be worth pursuing would be to find several real-world examples of packages with compatible documentation comments where old versions of the package would also compile with Swift 5.6? The best place to start that search would be with some of the long-time maintained packages that are on higher major version numbers. Is that something you'd be interested in starting to look for, or did you already have some in mind?