From f24bd81db8df78e98254c6f6b3f678e300a91be3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Tue, 15 Oct 2024 19:51:56 +0200 Subject: [PATCH 1/8] Update contributor documentation about documentation input discovery --- Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md | 2 +- .../SwiftDocC/CompilerPipeline.md | 30 ++++--- .../SwiftDocC/DocumentationContextGroup.md | 26 +++--- .../SwiftDocC/DocumentationWorkspaceGroup.md | 72 ---------------- .../SwiftDocC/InputDiscovery.md | 86 +++++++++++++++++++ 5 files changed, 115 insertions(+), 101 deletions(-) delete mode 100644 Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationWorkspaceGroup.md create mode 100644 Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/InputDiscovery.md diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md index 66fe6aeb60..cb35223aa5 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md @@ -22,7 +22,7 @@ SwiftDocC provides the APIs you use to load a bundle, parse the symbol-graph met ### Content Discovery -- +- - ### Resolving documentation links diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md index 9880623bfe..34b1c1a3e9 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md @@ -6,23 +6,24 @@ Get to know the steps involved in documentation compilation. This article describes the discrete and sequential steps of compiling documentation with DocC. -DocC starts with content discovery by parsing the documentation sources in your documentation bundle. Next, it validates and semantically analyzes them and then builds an in-memory model of the compiled documentation. Once the in-memory model is finalized, DocC converts each topic into a persistable representation it can store on disk. - -To use the compiled documentation, either query the in-memory model directly or convert its nodes to their render-friendly representation. For example, the `SwiftDocCUtilities` framework enumerates all the nodes in DocC's in-memory model, converts each node for rendering, and finally writes the complete documentation to the disk. +DocC starts with input discovery by categorizing the documentation sources in your documentation catalog. Next, it loads and parses the those inputs to create in-memory models of the documentation pages. Once the in-memory model is finalized, DocC converts each topic into a persistable render-friendly representation it can store on disk. ### Discovery -DocC starts discovery by creating a ``DocumentationWorkspace`` to interact with the file system and a ``DocumentationContext`` that manages the in-memory model for the built documentation. +DocC starts by creating a ``DocumentationContext/InputsProvider`` to discover the inputs from the user-provided command line arguments. These inputs are: -When a documentation bundle is found in the workspace by a ``DocumentationWorkspaceDataProvider``, the following files are recognized and processed (others are ignored): + - Markup files, tutorial files, and assets (for example images) + - Symbol graph files, describing the symbols in a given module (types, functions, variables, etc.) and their relationships (inheritance, conformance, etc.) + - Meta information about this "unit" of documentation (for example a custom display name) + - Customizations to the render template. -- An `Info.plist` file containing meta information like the bundle display name. -- Symbol-graph files with the `.symbols.json` extension. -- Authored markup files with an `.md` extension -- Authored tutorial files with a `.tutorial` extension -- Additional documentation assets with known extensions like `.png`, `.jpg`, `.mov`, and `.zip`. +Markup, tutorials, assets, and render-template-customization can only be discovered as files inside of a documentation catalog (`.docc` directory). +Symbol graph files can either be discovered as files inside of a documentation catalog or as additional files provided via user-provided command line arguments. +Meta information can either be discovered from an optional top-level `Info.plist` file inside of a documentation catalog or as provided values via user-provided command line arguments. All meta information is optional. -You can organize the files in any way, as long as `Info.plist` is in the root of the directory tree. Here is an example of a bundle, that groups topic files in logical groups with an additional directory for shared asset files: +You can organize the files inside the documentation catalog according to your preference, +as long as the optional `Info.plist`--containing optional meta information--and the optional render customization files are top-level. +For example, this catalog groups files based on their topic with an additional directory for shared asset files: ```none SwiftDocC.docc @@ -45,9 +46,10 @@ SwiftDocC.docc ### Analysis and Registration -This phase starts with registering all symbols from the available symbol graphs into a documentation *topic graph* in memory. +This phase starts with creating a ``DocumentationContext`` using the discovered inputs from the previous phase. +This begins loading and registering the inputs with the context. -The symbol graph files are machine generated and describe all available symbols in a framework (types, functions, variables, etc.) and their relationships, for example, inheritance and conformance. +The first input that the context register is the symbol information. The symbol information comes from "symbol graph files" which are machine generated and describe all available symbols in a framework (types, functions, variables, etc.) and their relationships (inheritance, conformance, etc.). Each symbol becomes a documentation node in the topic graph and thus a documentation *topic* (an entity in the documentation model). The symbol's topic could optionally be extended with authored documentation from a markup file. @@ -57,7 +59,7 @@ Next, all the remaining markup files are analyzed and converted to documents (fo Finally, if you reference any symbols from another framework, and DocC knows how to resolve those, the symbols are fetched and added to the graph too. -### Curation +#### Curation At this point the in-memory topic graph accurately represents the machine generated description of the documented framework. However, documentation is often better consumed when it's curated into logical groups and into an incremental learning experience. diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationContextGroup.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationContextGroup.md index da4e632315..3b2b3fa6bb 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationContextGroup.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationContextGroup.md @@ -4,8 +4,9 @@ Build and query the in-memory documentation model. ## Discussion -The documentation context generally manages the in-memory documentation including: - +A documentation context is the the in-memory representation of a "unit" of documentation (for example a module, package, or technology). +The context is generally responsible for: + - Analyzing bundle file contents and converting to semantic models. - Managing a graph of documentation nodes (a single node representing one documentation topic). - Processing assets like media files or download archives. @@ -14,12 +15,17 @@ The documentation context generally manages the in-memory documentation includin ### Creating a Context +Use ``DocumentationContext/init(bundle:dataProvider:diagnosticEngine:configuration:)`` to create a context for a given bundle: + ```swift -let workspace = DocumentationWorkspace() -let context = try DocumentationContext(dataProvider: workspace) -``` +let inputsProvider = DocumentationContext.InputsProvider() +let (bundle, dataProvider) = try inputsProvider.inputsAndDataProvider( + startingPoint: catalogURL, + options: bundleDiscoveryOptions +) -During initialization the context will inspect the available bundles in the workspace and load any symbol graph files and markup files. +let context = try DocumentationContext(bundle: bundle, dataProvider: dataProvider) +``` ### Accessing Documentation @@ -40,19 +46,11 @@ To find out the location of the source file for a given documentation node use: let sourceFileURL = try context.documentURL(for: reference) ``` -And finally to print all known paths in the context: - -```swift -context.knownIdentifiers.forEach({ print($0) }) -``` - ## Topics ### Documentation Context - ``DocumentationContext`` -- ``DocumentationContextDataProvider`` -- ``DocumentationContextDataProviderDelegate`` - ``AutomaticCuration`` ### Documentation Nodes diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationWorkspaceGroup.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationWorkspaceGroup.md deleted file mode 100644 index 4087dd21de..0000000000 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationWorkspaceGroup.md +++ /dev/null @@ -1,72 +0,0 @@ -# Bundle Discovery - -Learn how to explore a documentation workspace and discover bundles. - -## Discussion - -A ``DocumentationWorkspace`` manages a list of data providers that discover, register, and provide data access to documentation bundles. The data provider protocol ``DocumentationWorkspaceDataProvider`` does not make any assumptions regarding the documentation storage medium as long as the provider can identify those resources by their `URL`. - -A common case is to use the pre-defined ``LocalFileSystemDataProvider`` that loads any documentation bundles found in a given directory on disk: - -```swift -let workspace = DocumentationWorkspace() -let dataProvider = try LocalFileSystemDataProvider(rootURL: sourceDirectoryURL) -try workspace.registerProvider(dataProvider) - -guard let firstBundle = workspace.bundles.values.first else { - fatalError("No documentation bundle found") -} - -print("A bundle with ID: \(firstBundle.identifier)") - -print("Symbol graph files:") -print(firstBundle.symbolGraphURLs) -``` - -### Bundle Contents - -A ``DocumentationBundle`` offers the information needed to load its contents into memory for processing. A bundle is uniquely identified by its ``BundleIdentifier`` identifier. - -Use the bundle data to load symbol graphs, markup files, assets like images or videos, and bundle metadata. - -```swift -bundle.miscResourceURLs - .filter { $0.lastPathComponent.hasSuffix(".zip") } - .forEach { - print("Download archive: \($0.lastPathComponent)") - } -``` - -## Topics - -### Workspaces - -- ``DocumentationWorkspace`` -- ``DocumentationWorkspaceDataProvider`` - -### File Data Providers - -- ``FileSystemProvider`` -- ``LocalFileSystemDataProvider`` -- ``PrebuiltLocalFileSystemDataProvider`` -- ``FSNode`` - -### Documentation Bundles - -- ``DocumentationBundle`` -- ``BundleIdentifier`` -- ``DocumentationBundleFileTypes`` - -### Bundle Assets - -- ``DataTraitCollection`` -- ``DataAsset`` -- ``BundleData`` - -### Bundle Metadata - -- ``ExternalMetadata`` -- ``DefaultAvailability`` -- ``PlatformVersion`` - - diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/InputDiscovery.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/InputDiscovery.md new file mode 100644 index 0000000000..80d38636c0 --- /dev/null +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/InputDiscovery.md @@ -0,0 +1,86 @@ +# Input Discovery + +Learn how to discover documentation inputs on the file system. + +## Discussion + +A ``DocumentationContext/InputsProvider`` discovers documentation catalogs on the file system and creates a ``DocumentationBundle`` from the discovered catalog content. + +```swift +let inputProvider = DocumentationContext.InputsProvider(fileManager: fileSystem) + +guard let catalogURL = try inputProvider.findCatalog(startingPoint: startingPoint) else { + return +} +let bundle = try inputProvider.makeInputs(contentOf: catalogURL, options: BundleDiscoveryOptions()) + +print("A bundle with ID: \(bundle.identifier)") +``` + +You can also create documentation inputs, without a documentation catalog, from a list of symbol graph files: + +```swift +let inputProvider = DocumentationContext.InputsProvider(fileManager: fileSystem) + +guard let (bundle, dataProvider) = try inputProvider.makeInputsFromSymbolGraphs( + options: BundleDiscoveryOptions( + additionalSymbolGraphFiles: listOfSymbolGraphLocations + ) +) else { + return +} + +print("A bundle with ID: \(bundle.identifier)") +``` + +> Note: use the returned `dataProvider` to create a ``DocumentationContext`` from this ``DocumentationBundle``. + +It's common to want combine these two strategies and require that they discover a ``DocumentationBundle``. +For this use-case, use the +``DocumentationContext/InputsProvider/inputsAndDataProvider(startingPoint:allowArbitraryCatalogDirectories:options:)`` method: + +```swift +let inputProvider = DocumentationContext.InputsProvider(fileManager: fileSystem) + +let (bundle, dataProvider) = try inputProvider.inputsAndDataProvider( + startingPoint: maybeStartingPoint, + options: BundleDiscoveryOptions( + additionalSymbolGraphFiles: listOfSymbolGraphLocations + ) +) + +print("A bundle with ID: \(bundle.identifier)") +``` + +### Bundle Contents + +A ``DocumentationBundle`` represents the list of "discovered" input files--categorized by their kind--to use as documentation inputs. + +Use a ``DataProvider`` that the ``DocumentationContext/InputsProvider`` returned alongside the bundle to read the files in the bundle. + +## Topics + +### Input Discovery + +- ``DocumentationContext/InputsProvider`` +- ``DocumentationContext/InputsProvider/inputsAndDataProvider(startingPoint:allowArbitraryCatalogDirectories:options:)`` + +### Documentation Bundle + +- ``DocumentationBundle`` +- ``BundleIdentifier`` +- ``DocumentationBundleFileTypes`` + +### Bundle Assets + +- ``DataTraitCollection`` +- ``DataAsset`` +- ``BundleData`` + +### Bundle Metadata + +- ``ExternalMetadata`` +- ``DefaultAvailability`` +- ``PlatformVersion`` + + From 18cd622952e3124e552d46c7a396e91729167b03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Mon, 28 Oct 2024 13:32:13 +0100 Subject: [PATCH 2/8] Update copyright year for updated contributor documentation article --- Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md index 34b1c1a3e9..22ccb5ce4c 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md @@ -104,4 +104,4 @@ The file hierarchy under the output path represents the complete, compiled docum ╰ videos ``` - + From 975dac95413d6f193f997924da03a49d577d1421 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Mon, 28 Oct 2024 13:33:04 +0100 Subject: [PATCH 3/8] Avoid deprecated API in code example in contributor documentation --- .../SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md index b95f4e9059..e08c6a54d6 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md @@ -10,8 +10,7 @@ The ``DocumentationNodeConverter`` type converts documentation nodes to renderin ```swift let converter = DocumentationNodeConverter(bundle: myBundle, context: myContext) -let renderNode = converter.convert(documentationNode, - at: sourceURL, from: bundle) +let renderNode = converter.convert(documentationNode) ``` The render nodes can be persisted on disk as JSON files via `JSONEncodingRenderNodeWriter`: From 0e4ec7b9a1c2209d39682f52771df9c97d20d82d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Mon, 28 Oct 2024 13:34:44 +0100 Subject: [PATCH 4/8] Mention catalog content file extensions in top-level contributor documentation --- Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md index cb35223aa5..56a073d194 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md @@ -6,13 +6,13 @@ Combine code comments with markup prose to produce structured, semantic document DocC comes with built-in support for several types of input files. You organize these files by placing them in a folder with a `.docc` extension. This folder is called a documentation bundle, and can include these file types: - - Symbol-graph files, in JSON format, that describe available symbols in a framework. - - Lightweight markdown files that contain free-form articles and more. - - Tutorial files that include dynamic, learning content. - - Asset files like images, videos, and archived projects for download. - - An `Info.plist` file that contains metadata about the bundle. + - 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 load a bundle, parse the symbol-graph meta-information, extract symbol documentation, and optionally 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 From 34fb986dc76c49ecb028be060a87769270df3473 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Mon, 28 Oct 2024 13:51:07 +0100 Subject: [PATCH 5/8] Add more documentation for `DocumentationContext/InputsProvider` --- .../DocumentationInputsProvider.swift | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/Sources/SwiftDocC/Infrastructure/Input Discovery/DocumentationInputsProvider.swift b/Sources/SwiftDocC/Infrastructure/Input Discovery/DocumentationInputsProvider.swift index a08bd5f6ee..ae16ce51da 100644 --- a/Sources/SwiftDocC/Infrastructure/Input Discovery/DocumentationInputsProvider.swift +++ b/Sources/SwiftDocC/Infrastructure/Input Discovery/DocumentationInputsProvider.swift @@ -14,6 +14,43 @@ import SymbolKit extension DocumentationContext { /// A type that provides inputs for a unit of documentation. + /// + /// The inputs provider discovers documentation catalogs on the file system and creates a ``DocumentationBundle`` from the discovered catalog content. + /// + /// The input provider categorizes the catalog content based on corresponding ``DocumentationBundleFileTypes`` conditions: + /// + /// Category | Condition + /// ---------------------------------------- | ------------------------------------------------- + /// ``DocumentationBundle/markupURLs`` | ``DocumentationBundleFileTypes/isMarkupFile(_:)`` + /// ``DocumentationBundle/symbolGraphURLs`` | ``DocumentationBundleFileTypes/isSymbolGraphFile(_:)`` + /// ``DocumentationBundle/info`` | ``DocumentationBundleFileTypes/isInfoPlistFile(_:)`` + /// ``DocumentationBundle/themeSettings`` | ``DocumentationBundleFileTypes/isThemeSettingsFile(_:)`` + /// ``DocumentationBundle/customHeader`` | ``DocumentationBundleFileTypes/isCustomHeader(_:)`` + /// ``DocumentationBundle/customFooter`` | ``DocumentationBundleFileTypes/isCustomFooter(_:)`` + /// ``DocumentationBundle/miscResourceURLs`` | Any file not already matched above. + /// + /// ## Topics + /// + /// ### Catalog discovery + /// + /// Discover documentation catalogs and create documentation build inputs from the discovered catalog's content. + /// + /// - ``findCatalog(startingPoint:allowArbitraryCatalogDirectories:)`` + /// - ``makeInputs(contentOf:options:)`` + /// + /// ### Input discovery + /// + /// Discover documentation build inputs from a mix of discovered documentation catalogs and other command line options. + /// + /// - ``inputsAndDataProvider(startingPoint:allowArbitraryCatalogDirectories:options:)`` + /// + /// ### Errors + /// + /// Errors that the inputs provider can raise while validating the discovered inputs. + /// + /// - ``MultipleCatalogsError`` + /// - ``NotEnoughInformationError`` + /// - ``InputsFromSymbolGraphError`` package struct InputsProvider { /// The file manager that the provider uses to read file and directory contents from the file system. private var fileManager: FileManagerProtocol From bc0565886625bbca2cb2c06babb0ebcc7a1ad03e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Mon, 28 Oct 2024 13:52:00 +0100 Subject: [PATCH 6/8] Correct "catalog" terminology in some contributor documentation --- Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md | 4 +++- Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Benchmarking.md | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md index 56a073d194..439b14ab10 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md @@ -4,7 +4,7 @@ Combine code comments with markup prose to produce structured, semantic document ## Overview -DocC comes with built-in support for several types of input files. You organize these files by placing them in a folder with a `.docc` extension. This folder is called a documentation bundle, and can include these file types: +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. @@ -13,6 +13,8 @@ DocC comes with built-in support for several types of input files. You organize - 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 diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Benchmarking.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Benchmarking.md index 6460de90a8..7f97baff97 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Benchmarking.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Benchmarking.md @@ -8,7 +8,7 @@ When you are working on a PR to add a feature or fix a bug you should evaluate t ## Running a benchmark -To benchmark the `convert` command with a given documentation bundle `MyFramework.docc` run: +To benchmark the `convert` command with a given documentation catalog `MyFramework.docc` run: ``` swift run --package-path bin/benchmark benchmark --docc-arguments convert MyFramework.docc @@ -80,4 +80,4 @@ benchmark(add: BundlesCount(context: context)) - ``benchmark(end:benchmarkLog:)`` - ``benchmark(wrap:benchmarkLog:body:)`` - + From f3aad9ddd27fa13fc3d8de56f0bbcf0a5ffdb079 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Mon, 28 Oct 2024 13:52:53 +0100 Subject: [PATCH 7/8] Add more documentation for `DocumentationBundle` --- .../Infrastructure/DocumentationBundle.swift | 88 +++++++++++-------- 1 file changed, 52 insertions(+), 36 deletions(-) diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift b/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift index ce987274c9..cdc2dae2d2 100644 --- a/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift +++ b/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift @@ -10,20 +10,30 @@ import Foundation -/** - A documentation bundle. - - A documentation bundle stores all of the authored content and metadata for a collection of topics and/or frameworks. - - No content data is immediately loaded when creating a `DocumentationBundle` except for its `Info.plist`. Its purpose is to provide paths on disk for documentation resources. - - ## Topics - ### Bundle Metadata - - - ``displayName`` - - ``identifier`` - - ``version`` - */ +/// A collection of the build inputs for a unit of documentation. +/// +/// A unit of documentation may for example cover a framework, library, or tool. +/// Projects or packages may have multiple units of documentation to represent the different consumable products in that project or package. +/// +/// ## Topics +/// +/// ### Input files +/// +/// - ``markupURLs`` +/// - ``symbolGraphURLs`` +/// - ``miscResourceURLs`` +/// +/// ### Render customization +/// +/// - ``customHeader`` +/// - ``customFooter`` +/// - ``themeSettings`` +/// +/// ### Metadata +/// +/// - ``info`` +/// - ``displayName`` +/// - ``identifier`` public struct DocumentationBundle { public enum PropertyListError: DescribedError { case invalidVersionString(String) @@ -39,21 +49,17 @@ public struct DocumentationBundle { } } - /// Information about this documentation bundle that's unrelated to its documentation content. + /// Non-content information or metadata about this unit of documentation. public let info: Info - /** - The bundle's human-readable display name. - */ + /// A human-readable display name for this unit of documentation. public var displayName: String { info.displayName } - /** - The documentation bundle identifier. - - An identifier string that specifies the app type of the bundle. The string should be in reverse DNS format using only the Roman alphabet in upper and lower case (A–Z, a–z), the dot (“.”), and the hyphen (“-”). - */ + /// A identifier for this unit of documentation + /// + /// The string is typically in reverse DNS format using only the Roman alphabet in upper and lower case (A–Z, a–z), the dot (“.”), and the hyphen (“-”). public var identifier: String { info.identifier } @@ -72,13 +78,25 @@ public struct DocumentationBundle { @available(*, deprecated, message: "This deprecated API will be removed after 6.1 is released") public var attributedCodeListings: [String: AttributedCodeListing] = [:] - /// Symbol Graph JSON files for the modules documented by this bundle. + /// Symbol graph JSON input files for the module that's represented by this unit of documentation. + /// + /// Tutorial or article-only documentation won't have any symbol graph JSON files. + /// + /// ## See Also + /// + /// - ``DocumentationBundleFileTypes/isSymbolGraphFile(_:)`` public let symbolGraphURLs: [URL] - /// DocC Markup files of the bundle. + /// Documentation markup input files for this unit of documentation. + /// + /// Documentation markup files include both articles, documentation extension files, and tutorial files. + /// + /// ## See Also + /// + /// - ``DocumentationBundleFileTypes/isMarkupFile(_:)`` public let markupURLs: [URL] - /// Miscellaneous resources of the bundle. + /// Miscellaneous resources (for example images, videos, or downloadable assets) for this unit of documentation. public let miscResourceURLs: [URL] /// A custom HTML file to use as the header for rendered output. @@ -90,21 +108,19 @@ public struct DocumentationBundle { /// A custom JSON settings file used to theme renderer output. public let themeSettings: URL? - /** - A URL prefix to be appended to the relative presentation URL. - - This is used when a bundle's documentation is hosted in a known location. - */ + /// A URL prefix to be appended to the relative presentation URL. + /// + /// This is used when a built documentation is hosted in a known location. public let baseURL: URL - /// Creates a documentation bundle. + /// Creates a new collection of build inputs for a unit of documentation. /// /// - Parameters: - /// - info: Information about the bundle. + /// - info: Non-content information or metadata about this unit of documentation. /// - baseURL: A URL prefix to be appended to the relative presentation URL. - /// - symbolGraphURLs: Symbol Graph JSON files for the modules documented by the bundle. - /// - markupURLs: DocC Markup files of the bundle. - /// - miscResourceURLs: Miscellaneous resources of the bundle. + /// - symbolGraphURLs: Symbol graph JSON input files for the module that's represented by this unit of documentation. + /// - markupURLs: Documentation markup input files for this unit of documentation. + /// - miscResourceURLs: Miscellaneous resources (for example images, videos, or downloadable assets) for this unit of documentation. /// - customHeader: A custom HTML file to use as the header for rendered output. /// - customFooter: A custom HTML file to use as the footer for rendered output. /// - themeSettings: A custom JSON settings file used to theme renderer output. From b6a2079e9a3c285dfa8d28b5324006bd9ee445a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Mon, 28 Oct 2024 09:31:10 +0100 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Maya Epps <53411851+mayaepps@users.noreply.github.com> --- .../SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md index 22ccb5ce4c..eb63941f1b 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md @@ -6,7 +6,7 @@ Get to know the steps involved in documentation compilation. This article describes the discrete and sequential steps of compiling documentation with DocC. -DocC starts with input discovery by categorizing the documentation sources in your documentation catalog. Next, it loads and parses the those inputs to create in-memory models of the documentation pages. Once the in-memory model is finalized, DocC converts each topic into a persistable render-friendly representation it can store on disk. +DocC starts with input discovery by categorizing the documentation sources in your documentation catalog. Next, it loads and parses the those inputs to create in-memory models of the documentation pages. Once the in-memory model is finalized, DocC converts each topic into a persistable, render-friendly representation it can store on disk. ### Discovery @@ -49,7 +49,7 @@ SwiftDocC.docc This phase starts with creating a ``DocumentationContext`` using the discovered inputs from the previous phase. This begins loading and registering the inputs with the context. -The first input that the context register is the symbol information. The symbol information comes from "symbol graph files" which are machine generated and describe all available symbols in a framework (types, functions, variables, etc.) and their relationships (inheritance, conformance, etc.). +The first input that the context registers is the symbol information. The symbol information comes from "symbol graph files" which are machine generated and describe all available symbols in a framework (types, functions, variables, etc.) and their relationships (inheritance, conformance, etc.). Each symbol becomes a documentation node in the topic graph and thus a documentation *topic* (an entity in the documentation model). The symbol's topic could optionally be extended with authored documentation from a markup file.