enum DependencyInclusionPolicy Dependencystruct ThemeConfiguration ThemeConfigure DocCStatic for your documentation needs.
The Configuration Reference type controls all aspects of documentation generation, from which targets to document to the visual appearance of the output.
At minimum, you need to specify the package and output directories:
let configuration = Configuration(
packageDirectory: URL(fileURLWithPath: "/path/to/package"),
outputDirectory: URL(fileURLWithPath: "/path/to/docs")
)
By default, DocCStatic documents all targets in your package. To document specific targets only:
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
targets: ["MyLibrary", "MyUtilities"]
)
Control which dependencies are included using Dependency:
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
dependencyPolicy: .all
)
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
dependencyPolicy: .exclude(["LargeDependency", "InternalOnly"])
)
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
dependencyPolicy: .includeOnly(["PublicAPI"])
)
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
dependencyPolicy: .none
)
Link to the hosted documentation of dependencies that are not documented:
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
dependencyPolicy: .exclude(["MyDependency"]),
externalDocumentationURLs: [
"MyDependency": URL(string: "https://example.com/mydependency")!
]
)
When a page refers to a symbol of a module that is not part of the generated documentation, the reference links to the symbol’s page below the module’s base URL, at <base URL>/documentation/<module>/<path>/. A key is a module name or the name or identity of a package, which covers all modules of that package. References to modules without a base URL are shown as unlinked text. See Cross-Package Linking for details.
Enable client-side search with Lunr.js:
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
includeSearch: true
)
When search is enabled, the generator:
Creates a search-index file with all searchable content
Includes the Lunr.js library
Lists content matches below the tree when the reader types in the filter field of the navigation sidebar
Provides incremental search across all documentation
Customise the visual appearance with Theme. See Custom Themes for theme files, theme directories and feature switches.
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
theme: ThemeConfiguration(builtInTheme: .classic)
)
resolve resolves a string the same way as the --theme option: a theme directory, a theme-settings file, or the exact name or alias of a built-in theme.
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
theme: try ThemeConfiguration.resolveTheme("MyTheme")
)
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
theme: ThemeConfiguration(
accentColour: "#ff5500",
includeDarkMode: true
)
)
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
theme: ThemeConfiguration(builtInTheme: .default, includeDarkMode: false)
)
Append custom CSS after the theme’s own stylesheets:
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
theme: ThemeConfiguration(
builtInTheme: .default,
customCSS: """
.my-custom-class {
font-weight: bold;
}
"""
)
)
Enable detailled logging during generation:
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
isVerbose: true
)
This outputs progress messages including:
Symbol graph generation status
DocC conversion progress
Page rendering information
Asset writing confirmation
A fully-configured example:
let configuration = Configuration(
packageDirectory: URL(fileURLWithPath: "."),
outputDirectory: URL(fileURLWithPath: ".build/docs"),
targets: ["MyLibrary"],
dependencyPolicy: .exclude(["TestSupport"]),
externalDocumentationURLs: [
"MyDependency": URL(string: "https://example.com/mydependency")!
],
includeSearch: true,
theme: ThemeConfiguration(
accentColour: "#007aff",
includeDarkMode: true,
customCSS: ".header { background: linear-gradient(...); }"
),
isVerbose: true
)
enum DependencyInclusionPolicy Dependencystruct ThemeConfiguration Theme