Skip Navigation
ArticleArticle

Getting Started with DocCStatic

Use the DocCStatic library to generate static documentation programmatically.

Overview

The DocCStatic library provides a Swift API for generating static HTML/CSS documentation from Swift packages. Use it when you need programmatic control over the documentation generation process, such as integrating into custom build systems or creating documentation tooling.

Adding DocCStatic to Your Project

Add DocCStatic as a dependency in your Package.swift:

dependencies: [
    .package(url: "https://github.com/mipalgu/swift-docc-static.git", from: "1.0.0"),
]

For a command-line tool or script, add the product dependency:

.executableTarget(
    name: "MyDocTool",
    dependencies: [
        .product(name: "DocCStatic", package: "swift-docc-static"),
    ]
)

Configuring the Generator

Create a Configuration Reference with your package and output directories:

import DocCStatic

let configuration = Configuration(
    packageDirectory: URL(fileURLWithPath: "/path/to/my-package"),
    outputDirectory: URL(fileURLWithPath: "/path/to/docs")
)

Configuration Options

Customise the generation with additional options:

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    targets: ["MyLib", "MyOtherLib"],           // Specific targets only
    dependencyPolicy: .exclude(["SomeDep"]),    // Exclude specific deps
    includeSearch: true,                        // Enable Lunr.js search
    isVerbose: true                             // Verbose logging
)

See Configuration Reference for all available options.

Generating Documentation

Create a generator and call generate():

let generator = StaticDocumentationGenerator(configuration: configuration)

do {
    let result = try await generator.generate()
    print("Generated \(result.generatedPages) pages")
    print("Output: \(result.outputDirectory.path)")
} catch {
    print("Error: \(error)")
}

The generator returns a GenerationResult with statistics about the generated documentation.

Output Structure

The generator creates the following structure:

docs/
├── index.html              # Combined landing page
├── sidebar.html            # Navigation sidebar shared by all documentation pages
├── css/
│   └── main.css           # Stylesheet
├── js/
│   ├── lunr.min.js        # Search library (if enabled)
│   └── search.js          # Search functionality
├── documentation/
│   └── {module}/
│       ├── index.html     # Module overview
│       └── {symbol}/
│           └── index.html # Symbol documentation
└── search-index.json      # Search index (if enabled)

The navigation tree of all modules is written once, to sidebar.html. Each documentation page embeds it in a frame and selects its own entry through the URL fragment, so the current page is highlighted and its ancestors are expanded by the stylesheet alone. Readers can still expand and collapse every entry, with or without JavaScript. When JavaScript is available, the sidebar also offers a filter field, content search results (if search is enabled), and follows the appearance chosen on the page.

Rendering from Archives

If you have pre-generated DocC archives, render them directly:

let generator = StaticDocumentationGenerator(configuration: configuration)
let result = try await generator.renderFromArchive(archiveURL)

DocCStatic processes RenderNode instances from the DocC archive and converts them to static HTML.

Error Handling

The generator throws GenerationError for recoverable errors:

do {
    let result = try await generator.generate()
} catch let error as GenerationError {
    switch error {
    case .packageNotFound:
        print("Package.swift not found")
    case .buildFailed(let message):
        print("Build failed: \(message)")
    case .archiveParsingFailed(let message):
        print("Archive parsing failed: \(message)")
    }
} catch {
    print("Unexpected error: \(error)")
}

Next Steps

Alternatives

For simpler use cases, consider:

  • docc-static CLI - Command-line tool for direct usage

  • SPM Plugin - Integrated Swift Package Manager workflow