Unable to generate DocC documentation for swift-book

Development Swift-DocC
,
1

Hello, everyone.

I've created a project to translate TSPL book into Spanish (swiftbook.es). I originally set it up with Next.js and now I'm trying to make it look exactly like the original by forking the apple/swift-book repo and translating everything.

However, I'm getting some trouble generating documentation for GitHub pages. I think there's not enough information regarding that. The instructions for DocC mention a Package.swift file (which I don't see included in the swift-book repo). Following the existing instructions, I've created the Package.swift below and ran the following command via the Terminal: swift package --allow-writing-to-directory "docs/" generate-documentation --target "SwiftBookESWebsite" --disable-indexing --output-path "docs/" --transform-for-static-hosting --hosting-base-path "https://patternina.github.io/swift-book-es/".

// swift-tools-version: 5.8
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "swift-book-es-website",
    dependencies: [
        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")
    ],
    targets: [
        .target(
            name: "SwiftBookESWebsite",
            dependencies: [
                "swift-docc-plugin"
            ],
            path: "./TSPL.docc/.docc-build")
    ]
)

Here's the command output:

warning: 'swift-book-es': Source files for target SwiftBookESWebsite should be located under /Users/<username>/swift-book-es/TSPL.docc/.docc-build
warning: 'swift-book-es': Source files for target SwiftBookESWebsite should be located under /Users/<username>/swift-book-es/TSPL.docc/.docc-build
Building for debugging...
Build complete! (0.16s)
error: no target named 'SwiftBookESWebsite'

compatible targets: none

I'm sorry if this is simpler and I can't see it but I'm new to Packages and I don't think there's enough clarity on the instructions. Can anybody help me get this working?

2

Hey, I'd recommend taking a look at the bin/publish-book script. It boils down to running a command like this at the root of the repository:

docc convert \
    --experimental-enable-custom-templates \
    --hosting-base-path swift-book \
    --output-path swift-book \
    TSPL.docc

(You might need to make a swift-book directory at the root before you run that; the script does.)

We moved away from using a package format for the book because there weren't really any benefits to a documentation-only Swift package and it made the repo layout more complex.

1 Like