Static Hosting Support using DocC

I'm able to create my documentation via Xcode-> Product -> Build Documentation and that creates MY_PROJ.docarchive.

I can also create .docarchive using xcodebuild command

Now I'm trying to convert/export my .docarchive to host it in static space so that I can host it on Github pages. I'm using https://github.com/apple/swift-docc to convert my docarchive using the following command,

swift run docc process-archive transform-for-static-hosting <path/to/docarchive> --output-path <destination_path>

I can see the files exported in output-path which I believe is the files that I need to deploy in static hosting space.

But when I host the same files in my local server or Github pages, they are still blank. Not sure what's wrong here.

Replies

It is a little hard to say exactly what might be going wrong given this description, but it is a good sign if you can see that HTML files are emitted in the output path after running that command. There is no "root" page for DocC output at the moment, so it might be possible that you just didn't visit an appropriate URL path (example: /documentation/frameworkname). Although if you are truly seeing blank pages with no content at all, it may be worth checking to see if there are any JavaScript or other related errors being reported by your web browser.

One other potential issue is that maybe the version of Xcode you used to create the archive does not contain a recent version of DocC needed to support static hosting. To address that, you could update to the latest beta version of Xcode which would have this newer functionality and then use that to build your documentation for exporting the archive before running the process-archive command.

Also, you may need to also pass the --hosting-base-path argument if you intend to host the static site on a URL that includes a base path, like some GitHub Pages URLs may require (for example you may need to use something like --hosting-base-path /myrepo for a URL that needs to support something like /myrepo/documentation/frameworkname).

Hopefully some part of this information helps with your specific situation! You may also want to check out some recent related documentation for the DocC Swift Package Manager plugin at https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages

It's likely the base path is misconfigured. The resources all fail to load from the html file because the process-archive command prefixes the base path you pass it with a forward slash.