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:
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 Generation 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. 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 Generation 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