Running Xcode DocC without Apache Server/ (.htaccess)

Question

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/

Answer 1

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/"

Answer 2

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.

Answer 3

This is now documented in the SwiftDocCPlugin guide:

• Generating Documentation for Hosting Online

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.

• For using GitHub pages specifically: Publishing to GitHub Pages.

---

Example

• Example website hosted on GitHub pages
• GitHub repo

---

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.