I have an SPM package hosted at https://github.com/janodev/foobar
.
How can I generate documentation with Docc and host it at GitHub?
2025 update: still a convoluted process.
Start with a SPM package that has DocC documentation.
LLMAgent/
├──Sources/Documentation.docc
└──Package.swift
Build the renderer in a parent folder:
cd LLMAgent
# generate a distribution of swift-docc-render in a parent folder
cd ..
git clone https://github.com/swiftlang/swift-docc-render.git
cd swift-docc-render
mise install node@18.19.1
mise use node@18.19.1
npm install
npm run build
# go back to the project
cd ../LLMAgent
Project structure now:
.
├── LLMAgent/
│ └── Package.swift
└── swift-docc-render/
└── dist/
Add the DocC Plugin in LLMAgent/Package.swift. Note that I’m declaring the dependency but I don’t attach it to any target. This is intentional.
// swift-tools-version: 6.1
@preconcurrency import PackageDescription
let package = Package(
name: "LLMAgent",
products: [
.library(name: "LLMAgent", targets: ["LLMAgent"])
],
dependencies: [
.package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.4.3")
],
targets: [
.target(name: "LLMAgent")
]
Create a Makefile
PROJECT_NAME = LLMAgent
# ANSI colours for nice logs
BLUE = \033[34m
RESET = \033[0m
.PHONY: help
help:
@echo "$(BLUE)===== $(PROJECT_NAME) iOS Project Makefile =====$(RESET)"
@echo "$(BLUE)DOCC COMMANDS:$(RESET)"
@echo " make docc-archive - Generate DocC documentation archive to .docc-build/"
@echo " make docc-rendered - Build HTML docs ready to be hosted."
@echo " make preview-docs - Serve docs locally."
@echo " make deploy-docs - Deploy documentation to GitHub Pages"
# ===========================================
# DocC with swift-docc-render
# ===========================================
# Creates raw DocC HTML without styling or renderer. Not ready for hosting.
.PHONY: docc-archive
docc-archive:
@echo "$(BLUE)Generating DocC documentation archive...$(RESET)"
swift package \
--allow-writing-to-directory ./.docc-build \
generate-documentation \
--target $(PROJECT_NAME) \
--output-path ./.docc-build \
--transform-for-static-hosting \
--hosting-base-path $(PROJECT_NAME) \
--disable-indexing
@echo "$(BLUE)Documentation archive created at ./.docc-build$(RESET)"
# Creates the raw DocC and copies render assets.
.PHONY: docc-rendered
docc-rendered: docc-archive
@echo "CWD is: $(shell pwd)"
@echo "$(BLUE)Copying swift-docc-render assets into .docc-build...$(RESET)"
cp -a ../swift-docc-render/dist/. .docc-build/
@echo "$(BLUE)Documentation ready for static hosting with swift-docc-render$(RESET)"
# Show styled docs on a local server
.PHONY: preview-docs
preview-docs: docc-rendered
@echo "$(BLUE)Serving DocC documentation...$(RESET)"
@echo "Open your browser to http://localhost:8000/documentation/$(shell echo $(PROJECT_NAME) | tr '[:upper:]' '[:lower:]')"
cd .docc-build && python3 -m http.server
# Deploy documentation to GitHub Pages
.PHONY: deploy-docs
deploy-docs: docc-rendered
@echo "$(BLUE)Deploying DocC to GitHub Pages...$(RESET)"
ghp-import -n -p -f .docc-build
Run make
and read the instructions.
To deploy to GitHub you need to configure your repo:
Go to the pages setting of the project: https://github.com/janodev/LLMAgent/settings/pages
Select Branch: gh-pages
, / (root)
, and press Save
Run make deploy-docs
Open https://janodev.github.io/LLMAgent/documentation/llmagent
Mind the pattern: https://<username>.github.io/<repository>/documentation/<lowercase-project-name>
This is related to the flag --hosting-base-path LLMAgent
The whole process to publish to GitHub was
Your Code (LLMAgent) + DocC comments
↓
swift-docc-plugin (generate-documentation)
↓
.docc-build/ (raw HTML)
↓
+ swift-docc-render (frontend UI)
↓
.docc-build/ (fully styled static site)
↓
ghp-import (optional)
↓
🌍 GitHub Pages
Disregard the message below from ghp-import. GitHub Pages doesn’t require a pull request for gh-pages; the branch is already set up to serve content.
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote: https://github.com/janodevorg/CoreDataStack/pull/new/gh-pages
The gh-pages branch is now part of your repository. Each time you run make deploy-docs, ghp-import will update it.
Troubleshooting:
Be aware the browser cache may show a previous version of the website. Do a ⌘⇧R in Chrome to bypass it.
If you are enabling GitHub pages for the first time, it may take a few minutes.