3

In the DocC documentation, "Distributing Documentation to External Developers", Apple provided documentation to Host a Documentation Archive on Your Website. Unfortunately, when I open .doccarchive/index.html, I just get a white page. They have only shown guidance for Apache servers. They have specified using a .htaccess file, and using RewriteRule .* SlothCreator.doccarchive/$0 [L] to rewrite URLs when a user visits the documentation page.

Is there a way to open the documentation web app without running an Apache server? (I don't want to make any machine specific configuration like modifying /etc/hosts). It would be ideal to be able to host this as a static site (e.g. on Github pages, Cloudflare pages, Netlify, etc.)

Edit: With @Ranoiaetep's answer, I have built and pushed it to a GitHub repo and it can be viewed through a Netlify site: https://xcode-docc.netlify.app/documentation/

3

3 Answers 3

2

As of current, I don't think there's any option of hosting it as a static site.

However it is pretty easy to host it on Netlify with a .toml file set up:

[build]
publish = "ProjectName.doccarchive/"
###### Change it to your doccarchive file's name

[[redirects]]
from = "/documentation/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/tutorials/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/data/documentation.json"
status = 200
to = "/data/documentation/projectname.json"
###### Change it to name in ProjectName.doccarchive/data/documentation/...
# often just all lowercase of your project name

[[redirects]]
force = true
from = "/"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/documentation"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/tutorials"
status = 302
to = "/tutorials/"
3
  • I'm trying to just open the docs like a website/ html file to see how they look like (I don't know how Apple over looked this). To use your config, I built the SlothCreater.doccarchive locally (~30MB for SlothCreater) and tried serve it to Netlify, but how would you even serve static files in Netlify. I guess I should commit the build files (30MB, including large images). I think trying to get DocC to build in Netlify would be even harder, since it needs macOS/ xcodebuild. I would appreciate more help (though I hope your netlify.toml will come in handy later) Jun 25, 2021 at 22:14
  • @BenButterworth I didn't use Netlify cl tool. The way I did it, I just put the entire doccarchive file and the .toml file in the root folder of a GitHub repo. Then hosted that from netlify.com by selecting New site from Git. It will then ask for GitHub accesses, and it will build in just a few seconds.
    – Ranoiaetep
    Jun 25, 2021 at 22:19
  • 1
    Thanks for the help @Ranoiaetep, I've done the same: people can check it out at xcode-docc.netlify.app/documentation Jun 25, 2021 at 22:43
1

This is now documented in the SwiftDocCPlugin guide:

Transforming for Static Hosting

Alternatively, if you’d like to avoid setting custom routing rules on your server or are hosting in an environment where this isn’t possible, you can generate documentation that has been transformed for static hosting.


Example


Warning

You'll see a few Unfortunately's in this answer. I highly recommend you avoid using DocC for the reasons explained below. If you find workarounds to these, do let me know :). In terms of comparison, DocC competes with so many successful static site generators and open source documentation frameworks (Docusaurus) and doesn't do very well.


Steps

  • Add SwiftDocCPlugin to your Package.swift:
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
  • Build the site, run:
# Update to your target, from `Package.swift`
TARGET_NAME=SlothCreator
OUTPUT_DIR=docs
swift package --allow-writing-to-directory $OUTPUT_DIR \
    generate-documentation \
    --target $TARGET_NAME \
    --disable-indexing \
    --output-path $OUTPUT_DIR \
    --transform-for-static-hosting
  • cd docs
  • Run it locally:
    • You can start a server to serve your files: run python3 -m http.server.
    • Open the website in a browser: http://localhost:8000/documentation/target_name/
    • Warning: It still needs a webserver and the website doesn't work very well. If you visit http://localhost:8000, you get an error: The page you’re looking for can’t be found. You cannot just open the index.html page without a server.
  • Deploy it using GitHub pages, or Cloudflare Workers Sites:
    • When you deploy, this is taken care of, since GitHub pages, Cloudflare Workers Sites serve these pages. Unfortunately, this won't work with Cloudflare Pages, since it can't build Swift documentation.
  • Unfortunately, the paths is not configurable: /<output-path-specified-by-command-line>/documentation/<target-name>, for example, it could be: localhost:8000/documentation/slothcreator/
  • Unfortunately, you have to commit your generated documentation files into git. The Apple docs had shown the command: git add docs and git commit -m "Update GitHub pages documentation site.". This is because services like Github Pages, Cloudflare Workers Sites can't build your site for you.
  • Unfortunately, this generated folder (docs/) is 31MB and contains what appears to be unnecessary files and large, unoptimised assets. For some services eg Cloudflare Workers Sites, you have to upload the entire website every time you publish.
  • Unfortunately, you need to regenerate and commit all the files separately if you want to put them at different paths, since you need to use a different command. See comments in build.sh. This means it's not 31MB, but N x 31MB, where N is the number of sites you have.
2
  • 2
    Some things are correct, but committing static site content to git seems to be more of an issue with using GitHub Pages rather than the DocC CLI itself, similarly with a large site folder. Also, note I don't recommend to use the Swift-DocC-Plugin, we actually use the DocC CLI tool that comes with Xcode to enable support for apps. Also, the path actually is configurable with hosting-base-path, and there's no need to commit at different paths using the DocC CLI as outlined in my above answer. May 4, 2022 at 19:50
  • Hello 😃, 1. I am happy to commit files that are small. But when it's 31MB like DocC, I don't like it as much, DocC is not very optimised 😅. 2. Yes xcodebuild docbuild another option, but I am not too interested in it at the moment given that it will have similar issues. 3. The full path != hosting-base-path. You cannot remove /documentation/<target-name>, if you can, LMK 😊. Jun 8, 2022 at 9:32
0

Update for Xcode 13.3

That's a good question and wasn’t possible until recently enabled by the improvements in Xcode 13.3.

I've outlined multiple steps for DocC app/Package doccarchive deployment through GitHub Pages in my latest blog post.

There were several issues I had to resolve:

  1. Ensure generated docs URLs and hosted base paths are case-sensitive.
  2. Use xcodebuild -project ModularSlothCreator.xcodeproj -scheme ModularSlothCreator -parallelizeTargets docbuild to build a modular documentation archive.
  3. Use the transform-for-static-hosting flag provided by the docc cli ${xcrun docc} transform-for-static-hosting ...

For more details and a CI script, feel free to reference the blog post.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.