Framework

SwiftDocC

Combine code comments with markup prose to produce structured, semantic documentation.

Overview

DocC comes with built-in support for several types of input files. You group these files by placing them in a folder with a .docc extension. This folder is called a documentation catalog, and can include these file types:

Lightweight markdown files that contain free-form articles or additional symbol documentation, with an .md extension.
Tutorial files that include dynamic learning content, with a .tutorial extension.
Asset files like images, videos, and archived projects for download, with known extensions like .png, .jpg, .mov, and .zip.
Symbol-graph files that describe the symbols of your API, with an .symbols.json extension.
An Info.plist file with optional metadata about the documentation.
A theme-settings.json with theming customizations for the rendered output.

SwiftDocC provides the APIs you use to discover documentation inputs, load catalog content, parse the symbol-graph meta-information, extract symbol documentation, and pair that symbol documentation with external file content. DocC represents the compiled documentation in an in-memory model that you can further convert in a persistable representation for writing to disk.

Topics

Essentials

The Swift-DocC Pipeline

Get to know the steps involved in documentation compilation.

Content Discovery

Input Discovery

Learn how to discover documentation inputs on the file system.
Documentation Context

Build and query the in-memory documentation model.

Resolving documentation links

Linking Between Documentation

Connect documentation pages with documentation links.

Rendering

Converting in-memory documentation into rendering nodes and persisting them on disk as JSON.

Rendering Model

Convert documentation nodes into render nodes and save them to disk.
Persisting Documentation

Save compiled documentation to disk.

Indexing

Documentation Indexing

Create documentation indexes optimized for text search or navigation.

Diagnostics and Analysis

Emitting Diagnostics

Vend warnings and errors as part of an operation’s result.
Adding user-facing diagnostics

Display information to the developer about actionable issues with their documentation.
Static Analysis

Run static analysis checks on markup files.
Benchmarking

Produce performance metrics to improve the compilation pipeline and track regressions.

Utilities and Communication

Concurrency

Perform concurrent work on the DocC model.
Utility APIs
Communication Bridge

Offer native integration of DocC in your IDE.

Development

Indicating Feature Availability to Tools

Add features to DocC and indicate the feature’s availability to other tools.
Adding Feature Flags

Develop experimental features by adding feature flags.

Classes

class CustomMetadata
A directive that accepts an arbitrary key/value pair and emits it into the metadata of the page
class DiagnosticConsoleWriter
Writes diagnostic messages to a text output stream.
class DiagnosticFileWriter
A diagnostic consumer that writes detailed diagnostic information to a file.
class DocumentationContentRenderer
A collection of functions that render a piece of documentation content.
class DocumentationContextConverter
A converter from documentation nodes to render nodes.
class DocumentationServer
A server that provides documentation-related services.
class LinkResolver
A class that resolves documentation links by orchestrating calls to other link resolver implementations.
class Links
A directive for authoring authoring embedded previews of documentation links (similar to how links are currently rendered in Topics sections) anywhere on the page without affecting page curation behavior.
class Options
A directive to adjust Swift-DocC’s default behaviors when rendering a page.
class Row
A container directive that arranges content into a grid-based row and column layout.
class Small
A directive for specifying small print text like legal, license, or copyright text that should be rendered in a smaller font size.
class Snippet
Embeds a code example from the project’s code snippets.
class Synchronized
A wrapper type that ensures a synchronous access to a value.
class TabNavigator
A container directive that arranges content into a tab-based layout.

Protocols

protocol AnyLink
Any kind of Markdown.Markup element that has a destination property.
protocol BenchmarkBlockMetric
A metric that runs over a period of time and needs to be started and stopped to produce its result.
protocol BenchmarkMetric
A generic, named metric.
protocol ConvertOutputMarkdownConsumer
protocol DataProvider
A type that provides data for files.
protocol DiagnosticFormattingConsumer
A type that can format received diagnostics in way that’s suitable for writing to a destination such as a file or TextOutputStream.
protocol DocumentationServerProtocol
Protocol for request-response based servers.
protocol DocumentationService
A service for processing documentation requests.
protocol DynamicallyIdentifiableMetric
A metric which could dynamically provide a custom id and name.
protocol ExternalNodeConsumer
A consumer for nodes generated from external references.
protocol FileManagerProtocol
A read-write file manager.
protocol HTMLContentConsumer
A consumer for HTML content produced during documentation conversion.

Structures

struct AnchorSection
Section of a document that can be linked to.
struct AssetReference
A reference to an asset.
struct BenchmarkResult
A metric result which can be encoded.
struct BenchmarkResults
The results of a single benchmark run.
struct BuildMetadata
A value that encapsulates metadata for a documentation archive that DocC built.
struct CatalogDiscoveryOptions
Options to configure the discovery of documentation catalogs.
struct ChildDirective
A property wrapper that represents a child directive.
struct ChildMarkup
A property wrapper that represents general-purpose markup within a directive.
struct CodableContentSection
A Codable container for reference pages sections.
struct ConvertRequest
A request to convert in-memory documentation.
struct ConvertRequestContextWrapper
A wrapper type that adds contextual information relating to a convert request.
struct ConvertResponse
A response for a successful documentation conversion.
struct ConvertService
A service that converts documentation.
struct ConvertServiceError
An error that occurs during the processing of a documentation conversion request.
struct CoverageDataEntry
CoverageDataEntry represents coverage data for one symbol/USR.
struct CursorRange
A range in a document represented by a pair of line-column pairs.
struct DiagnosticFormattingOptions
A type that encapsulate the possible formatting options for diagnostics.
struct DictionaryKey
Documentation about a dictionary key for a symbol.
struct DictionaryKeysSection
A section that contains a dictionary’s keys.
struct DirectiveArgumentWrapped
A property wrapper that represents a directive argument.
struct DocumentationCoverageOptions
Resolves and validates the arguments needed to enable the documentation coverage feature.
struct DocumentationServerError
An error that occurs during the processing of a message by a documentation service.
struct ErrorsEncountered
A general error that indicates that at least one error was encountered while compiling documentation.
struct ExternalRenderNode
A rendering-friendly representation of a external node.
struct GeneratedCurationWriter
A type that writes the auto-generated curation into documentation extension files.
struct HTMLRenderer
A type that renders documentation pages into semantic HTML elements.
struct HTTPBody
Documentation about the payload body of an HTTP request.
struct HTTPBodySection
A section that contains a request’s upload body.
struct HTTPEndpointSection
A section that contains a request’s endpoint.
struct HTTPParameter
Documentation about a parameter for an HTTP request.
struct HTTPParametersSection
A section that contains an HTTP request’s parameters.
struct HTTPResponse
Documentation about the response for an HTTP request symbol.
struct HTTPResponsesSection
A section that contains an HTTP request’s responses.
struct Implementation
An intermediate model to group together an implementation reference, its parent, and a fallback name.
struct MarkdownOutputManifest
A manifest of markdown-generated documentation from a single catalog
struct MarkdownOutputNode
A markdown version of a documentation node.
struct MentionsRenderSection
struct NoOpLogMessage
struct NoOpLoggerShim
A shim for os.Logger that does nothing.
struct NoOpSignposterShim
A shim for os.OSSignposter that does nothing, except for running the passed interval task.
struct PrintCursor
The line and column of a position in text.
struct PropertyListDetailsRenderSection
A section that contains details about a property list key.
struct PropertyListPossibleValuesSection
struct RESTBodyRenderSection
A section that contains a REST request-body details.
struct RESTParametersRenderSection
A section that contains a list of REST parameters.
struct RESTResponse
A REST response that includes the HTTP status, reason, and the MIME type encoding of the response body.
struct RESTResponseRenderSection
A section that displays a list of REST responses.
struct RemoveHierarchyTransformation
This transformation removes the hierarchy information from a render node JSON, also getting rid of the dead references. It’s useful to save space when the hierarchy information is not a key information to preserve.
struct RenderContext
A context object that pre-renders commonly used pieces of content.
struct RenderReferenceDependencies
struct RenderReferenceStore
A storage for render reference information.
struct SerializableLinkResolutionInformation
An opaque container of link resolution information that can be encoded and decoded.
struct SourceRepository
A remote repository that hosts source code.
struct TopicColor
A color that associated with a documentation topic.
struct TopicImage
A custom authored image that can be associated with a documentation topic.
struct TopicReferenceResolutionErrorInfo
The error causing the failure in the resolution of a TopicReference .
struct WritableMarkdownOutputNode
struct XcodeRequirementReference
A reference to a version of Xcode that users of your documentation must use.

Enumerations

enum ConvertActionConverter
enum DocumentationCoverageLevel
Specifies whether the documentation coverage feature is enabled and, if it is, what amount of specificity is selected.
enum ExternalIdentifier
A convenience structure to represent an external identifier of a symbol.
enum LinkCompletionTools
A collection of API for link completion.
enum LogHandle
An object that writes logs to the given output device.
enum RESTParameterSource
A kind of a REST request parameter.
enum RenderJSONDecoder
A namespace for decoders for render node JSON.
enum RenderJSONEncoder
A namespace for encoders for render node JSON.