Support hosting DocC archives in static hosting environments

[ethankusters]

Hi @brianmichel!

Sorry to hear you're having trouble here.

@brianmichel

Does anyone here have an example of this working on GitHub Pages?

Here are a few examples of Swift-DocC docs up on GitHub Pages today:

• https://karwa.github.io/swift-url/main/documentation/weburl/
• https://apple.github.io/swift-argument-parser/documentation/argumentparser/
• https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/

@brianmichel

I end up having to browse to the path CoolCode/documentation/coolcode before I see anything rendering.

This is the expected behavior today. Because you passed --hosting-base-path CoolCode, the generated site expects to be hosted at the /CoolCode base path. This functionality is provided to support hosts like GitHub pages, where your site is essentially name-spaced by the name of your repo.

By default, we expect Swift-DocC docs on GitHub pages to be available at something like:

https://<username>.github.io/<repository-name>/documentation/<target-name>

Since you're using a simple Python HTTP server, you can skip the --hosting-base-path option, and access your docs directly at the root of your site (/documentation/coolcode) if you'd like.

There's a little more information around GitHub Pages hosting in the Swift-DocC Plugin's documentation here. It is written specific to the plugin's usecase but should still be broadly applicable.