Support hosting DocC archives in static hosting environments

Does this mean, for example, that I can compile ARHeadsetKit’s DocC catalog into HTML code tomorrow and host it on GitHub pages?

1 Like

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):

  • 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.
  • 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.
10 Likes

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 :see_no_evil:

4 Likes

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
cd swift-docc
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.

4 Likes

I’m thinking of using the new DocC to publish online documentation for my MetalFFT (GitHub - philipturner/metal-fft: 1D, 2D, and 3D variations of Fast Fourier Transforms) framework instead this weekend.

@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:

  • --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:

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.

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.

6 Likes

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 :-)

8 Likes

It would be awesome if multiple versions hosted together allowed users to see API diffs like the docs on developer.apple.com, example: Accessibility | Apple Developer Documentation

3 Likes

I look forward to using this to replace Google's archived documentation for Swift for TensorFlow.

2 Likes

Does anyone here have an example of this working on GitHub Pages? Every time I end up transforming a .doccarchive and hosting the result with a simple Python web server, I seem to have to go a few levels deep to actually see the generated documentation. Meaning if I generate documentation with the following command (assuming I'm generating multiple sets of documentation for all of our frameworks):

swift run docc process-archive transform-for-static-hosting CoolCode.doccarchive \ 
--output /path/to/output \
--hosting-base-path CoolCode

I end up having to browse to the path CoolCode/documentation/coolcode before I see anything rendering. I would assume if I generated multiple transformed archives into the same folder I could serve that folder and navigate to /CoolCode to see the documentation at the root level.

I was trying to follow the example from Support hosting DocC archives in static hosting environments - #27 by ethankusters to figure out a solution to host generated documentation for my team's many frameworks, but this doesn't seem to completely do it. Any thoughts?

(N.B. I'm running the latest sha's from both swift-docc and swift-docc-render to generate my examples)

Hi @brianmichel!

Sorry to hear you're having trouble here.

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

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.

4 Likes

Much appreciated Ethan, I figured I was doing something wrong. I'll give this a try!

1 Like

I didn't know it was possible today!

2 Likes

@brianmichel - Let me toss out three more:

I've been splatting a script into a docs-specific branch and rendering into the docs directory since that's a default that Github Pages supports easily.

One version uses the new Docc Plugin:

Another uses classic Docc convert:

With the pattern I've started using being to keep a docs branch "rebased" over the top of whatever current dev or release branch I'm documenting. I've written up a walk-through on my personal blog if you're so inclined.

7 Likes

To my understanding, a "--hosting-base-path" must be specified if the static files are hosted in a subfolder, is that correct?

We generate the static files on a build server and eventually copy it to the release server to a different sub path.
It would be good if we can preview the generated files directly on the build server, but it seems that would require specifying different --hosting-base-path's for build and release.

Is it possible to just arrange the generated static files in its hierarchy, without depending on a relative base path? Thanks.