Support hosting DocC archives in static hosting environments

[ethankusters]

@gwendal.roue

Full support for Github hosting would be convenient for so many reasons, but there is one more. Granting the right to publish an update to the doc is as easy as granting the right to modify the code: just grant a push access to the repository that contains the generated documentation. This will be really helpful for teams.

@gwendal.roue I agree! If there's anything you'd like to see beyond what is described in the original forums post that you would consider necessary for "Full support" of GitHub hosting, please let me know. This is a really important feature for Swift-DocC to get right.

Regarding your feature requests:

@gwendal.roue

• Ability to host several versions of the doc (so that users of an older version of a lib can still access the documentation for this version): http://author.github.com/repo/docs/1.0, http://author.github.com/repo/docs/2.1, etc.

Proper versioning support in Swift-DocC is definitely something we'd like to tackle in the future but you may be able to achieve something like what you're describing with what's supported today.

I haven't tried this- but I think this should be possible today with the --hosting-base-path flag described in the original post. I can imagine configuring your CI to pass a different base path depending on the current branch. So maybe:

• --hosting-base-path my-repo-name/main
• --hosting-base-path my-repo-name/v1.0
• --hosting-base-path my-repo-name/v1.5

And then storing the output in various root folders also depending on that branch like:

main
├ data
│  │ example.json
│  └ ...
├ documentation
│  ├ example
│  │   └ index.html
│  └ ...
├ js
├ css
└ ...
v1.0
├ data
│  └ ...
├ documentation
│  └ ...
└ ...
v1.5
└ ...

GitHub Pages would then make your documentation available at various base urls like:

• https://my-username.github.io/my-repo-name/main/documentation/MyFramework
• https://my-username.github.io/my-repo-name/v1.5/documentation/MyFramework
• https://my-username.github.io/my-repo-name/v2.0/documentation/MyFramework

This isn't a great user experience and there's a lot we can do to make this process easier when we address versioning more directly (and we're tracking some feedback like [SR-15541] Support hosting of multiple DocC archive(s) (versions) · Issue #204 · apple/swift-docc · GitHub on this) but I'm excited about the possibilities already.

@gwendal.roue

• The final lovely touch: document a way for the old versions of the doc to warn they are outdated, and to provide a link to the latest version, without regeneration.

I agree this would be amazing and is exactly what I've been thinking of as "proper" versioning support in Swift-DocC. I don't believe we're currently tracking this as a feature request- if you'd like to post some details on how you'd like this to work on bugs.swift.org and start a dedicated thread about it, I'd love to chat more.