iosswiftswift-package-managerdocc

How can I publish on GitHub using Docc?

I have an SPM package hosted at https://github.com/janodev/foobar.

How can I generate documentation with Docc and host it at GitHub?

Solution

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

    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: