Exiting to see this moving forward! Making hosting easier will probably increase DocC adoption significantly.
@ktoso Sorry to hear that- I definitely didn't intend for this to be misleading.
This work is designed to help support common hosting scenarios, like GitHub Pages, where Swift-DocC documentation hosting wasn't possible. It is explicitly not a rewrite of Swift-DocC's renderer. Swift-DocC-Render is a single page web application and continues to be even with this new hosting support.
This produces a DocC archive in the same format that is currently emitted. The only change is that we now duplicate the base index.html file that powers the Swift-DocC-Render SPA to all relevant file paths so that when a user navigates to a given path, we don't need custom routing to direct them to the single index.html at the root. You can see a copy of the current index.html here: Swift-DocC-Render-Artifact:index.html. That is the file that will be copied around.
This is currently described in the original post here but I agree that it could be more clear. There's some documentation on how DocC archives work on Swift.org here.
This is not the case for Swift-DocC-Render today or with the static-hosting support described here. From Swift-DocC-Render's README:
I think this is a good idea that we should explore when we do add support for emitting HTML directly. However, today, Swift-DocC only supports a single output format: RenderJSON. That JSON is then dynamically rendered by the Swift-DocC-Render SPA. So in the future, I could imagine us having both --output-format=json and --output-format=html.
I agree that "static hosting" terminology is unusual. But I think what we're doing here is a little unusual. We're not adding support for a new output format, we're transforming an existing one to enable new hosting scenarios.
This is a great point. I spoke with @marcus_ortiz and he agrees that the base-path option we're adding should not be specific to the static hosting transformation we're doing here. For example, there are users of Swift-DocC that would benefit from being able to customize the base path of Swift-DocC-Render but don't need the --transform-for-static-hosting support.
I think updating this flag from --static-hosting-base-path to just --hosting-base-path makes sense.
This definitely helps and is exactly the kind of feedback we're looking for. Thank you so much!
I think this is an interesting alternative solution where we could potentially use a URL system with paths appended as a fragment so that there truly only ever is one real HTML file needed.
Unfortunately, I think there are some downsides to this approach—the main one being that we would lose our current system where we have true URLs right now and don’t need to append the hash fragment for every single page since we would be bypassing the History web APIs. If we were to go with this approach, you may have to access pages like /#documentation/example instead of /documentation/example.
I think this approach might also run into the issue I touched on earlier in the thread with giving the ability to serve proper 200 and 404 responses based on the URL path.
Also, the logic for linking to other pages could be impacted, and it might conflict with how we already support URL fragments in our current URL system (like /documentation/example#overview as an example) for same page linking.
This feature should be high on the priority list. Right now, not being able to host documentation online forced me to maintain two duplicates of the code in ARHeadsetUtil. I also had to give extensive instructions to users of ARHeadsetKit to get documentation to compile properly in Xcode, and having it already exist on GitHub pages would make much more people inclined to try (or at least skim) the tutorials. I took the entire SwiftUI course on Apple's website, not in the Xcode documentation viewer, and I suspect that other people feel the same way.
To be clear, you can host the documentation online, it's just in a (IMO) quirky format that requires you to also support specific pathing redirects in whatever you're using to host it.
like Konrad, I'd love to see a future variation that has an end result of flat, static HTML being generated in a directory - which is far more akin to what other tools provide (sphinx, jazzy, asciidoc, hugo, etc).
Am I correct in thinking that "merged to main" means it'll be out with the next successful swift-nightly toolchain release? Or am I being too optimistic (I wasn't sure if there was another branch delay in there or such...)
You are correct! Now that Swift-DocC is part of the Swift toolchain, the repository's main branch is pulled every night for the nightly toolchain builds. So I would expect this to be included in the next successful build.
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.
I hope that Github hosting is planned to enter the end-to-end test suite of DocC.
Feature requests (just in case those use cases were not properly identified yet):
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. This would be really nice because as long as old versions of the doc are online, one can never tell which one Google will put in the results. Besides, immutable links to old versions will exist online (in online comments, forums posts, stack overflow answers, etc.). Telling the user he's looking at outdated documentation would be a nice touch. I agree that a well-designed robots.txt can help pruning old docs from the search engine indexes, but immutable links remain.
Huge +1 from me for supporting multiple versions. This is crucial for hosting documentation for any publicly available library. Although it is orthogonal to static hosting, I couldn't resist voicing my support for it here since you mentioned it
I hope that this is successful. I would like to have that process go easily, as I’m working on a different project right now and don’t want to spend a lot of time manually recompiling the ARHeadsetKit documentation.
You'll be able to use the next Swift.org nightly toolchain to produce DocC archives that are compatible with GitHub Pages. I’ll post in this thread with detailed instructions on how to use the new functionality when the first toolchain that includes these changes is released.
If you'd like to get a jump-start on things, you can pull Swift-DocC's main branch and use the latest version of docc to transform an existing DocC archive to make it compatible with GitHub pages. For example:
git clone https://github.com/apple/swift-docc.git
swift run docc transform-for-static-hosting <path-to-your-doccarchive> --hosting-base-path <github-repo-name>
This will transform an existing DocC archive to make it compatible with GitHub pages.
Again, once functionality this is available in a nightly toolchain, I’ll post instructions on how to create a new DocC archive that can be hosted on GitHub pages.
@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:
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:
And then storing the output in various root folders also depending on that branch like:
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.
Thank you very much @ethankusters. I'm very glad the team behind DocC shows such focus on user experience, not only UX for doc readers, but UX for doc producers as well. This level of empathy is quite refreshing :-)