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: