Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -520,7 +520,7 @@ For more in-depth technical information about Swift-DocC, please refer to the
project's technical documentation:

- [`SwiftDocC` framework documentation](https://swiftlang.github.io/swift-docc/documentation/swiftdocc/)
- [`SwiftDocCUtilities` framework documentation](https://swiftlang.github.io/swift-docc/documentation/swiftdoccutilities/)
- [`CommandLine` framework documentation](https://swiftlang.github.io/swift-docc/documentation/commandline/)

### Related Projects

Expand All @@ -545,4 +545,4 @@ project's technical documentation:
with support for building and viewing documentation for your framework and
its dependencies.

<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->
20 changes: 10 additions & 10 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
Expand Down Expand Up @@ -55,7 +55,7 @@ let package = Package(
name: "SwiftDocCTests",
dependencies: [
.target(name: "SwiftDocC"),
.target(name: "SwiftDocCTestUtilities"),
.target(name: "TestUtilities"),
],
resources: [
.copy("Test Resources"),
Expand All @@ -67,7 +67,7 @@ let package = Package(
),
// Command-line tool library
.target(
name: "SwiftDocCUtilities",
name: "CommandLine",
dependencies: [
.target(name: "SwiftDocC"),
.product(name: "NIOHTTP1", package: "swift-nio", condition: .when(platforms: [.macOS, .iOS, .linux, .android])),
Expand All @@ -77,11 +77,11 @@ let package = Package(
swiftSettings: swiftSettings
),
.testTarget(
name: "SwiftDocCUtilitiesTests",
name: "CommandLineTests",
dependencies: [
.target(name: "SwiftDocCUtilities"),
.target(name: "CommandLine"),
.target(name: "SwiftDocC"),
.target(name: "SwiftDocCTestUtilities"),
.target(name: "TestUtilities"),
],
resources: [
.copy("Test Resources"),
Expand All @@ -92,7 +92,7 @@ let package = Package(

// Test utility library
.target(
name: "SwiftDocCTestUtilities",
name: "TestUtilities",
dependencies: [
.target(name: "SwiftDocC"),
.product(name: "SymbolKit", package: "swift-docc-symbolkit"),
Expand All @@ -104,17 +104,17 @@ let package = Package(
.executableTarget(
name: "docc",
dependencies: [
.target(name: "SwiftDocCUtilities"),
.target(name: "CommandLine"),
],
exclude: ["CMakeLists.txt"],
swiftSettings: swiftSettings
),

// Test app for SwiftDocCUtilities
// Test app for CommandLine
.executableTarget(
name: "signal-test-app",
dependencies: [
.target(name: "SwiftDocCUtilities"),
.target(name: "CommandLine"),
],
path: "Tests/signal-test-app",
swiftSettings: swiftSettings
Expand Down
2 changes: 1 addition & 1 deletion Sources/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,5 @@ See https://swift.org/LICENSE.txt for license information
#]]

add_subdirectory(SwiftDocC)
add_subdirectory(SwiftDocCUtilities)
add_subdirectory(CommandLine)
add_subdirectory(docc)
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ public struct DocumentationCoverageOptionsArgument: ParsableArguments {
//
// It is safe to add a retroactively conformance here because the other module (SwiftDocC) is in the same package.
//
// These conforming types are defined in SwiftDocC and extended in SwiftDocCUtilities, because SwiftDocC doesn't link against ArgumentParse (since it isn't about CLI).
// These conforming types are defined in SwiftDocC and extended in CommandLine, because SwiftDocC doesn't link against ArgumentParser (since it isn't about CLI).
// We conform here because this is the first place that we can add the conformance. The implementation is in SwiftDocC.
extension SwiftDocC.DocumentationCoverageLevel: ArgumentParser.ExpressibleByArgument {}
extension SwiftDocC.DocumentationCoverageOptions.KindFilterOptions.BitFlagRepresentation: ArgumentParser.ExpressibleByArgument {}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# ``SwiftDocCUtilities``
# ``CommandLine``

Build custom documentation workflows by leveraging the DocC compiler pipeline.

## Overview

SwiftDocCUtilities provides a default, command-line workflow for DocC, powered by Swift [Argument Parser](https://apple.github.io/swift-argument-parser/documentation/argumentparser/). `docc` commands, such as `convert` and `preview`, are conformant ``Action`` types that use DocC to perform documentation tasks.
CommandLine provides a default, command-line workflow for DocC, powered by Swift [Argument Parser](https://apple.github.io/swift-argument-parser/documentation/argumentparser/). `docc` commands, such as `convert` and `preview`, are conformant ``Action`` types that use DocC to perform documentation tasks.

Use SwiftDocCUtilities to build a custom, command-line interface and extend it with additional commands. To add a new sub-command called `example`, create a conformant ``Action`` type, `ExampleAction`, that performs the desired work, and add it as a sub-command. Optionally, you can also reuse any of the provided actions like ``ConvertAction``.
Use CommandLine to build a custom, command-line interface and extend it with additional commands. To add a new sub-command called `example`, create a conformant ``Action`` type, `ExampleAction`, that performs the desired work, and add it as a sub-command. Optionally, you can also reuse any of the provided actions like ``ConvertAction``.

```swift
public import ArgumentParser
Expand Down Expand Up @@ -44,4 +44,4 @@ Adding a new sub-command automatically adds routing and execution of its code, a
- ``Throttle``
- ``Signal``

<!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->
<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# ``SwiftDocCUtilities/InitAction``
# ``InitAction``

@Metadata {
@DocumentationExtension(mergeBehavior: override)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# ``SwiftDocCUtilities/Docc``
# ``Docc``

## Topics

Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,12 @@ value so that the default initializer can be used.

### Feature flags on the command line

Command-line feature flags live in the `Docc.Convert.FeatureFlagOptions` in `SwiftDocCUtilities`.
Command-line feature flags live in the `Docc.Convert.FeatureFlagOptions` in `CommandLine`.
This type implements the `ParsableArguments` protocol from Swift Argument Parser to create an option
group for the `convert` and `preview` commands.

These options are then handled in `ConvertAction.init(fromConvertCommand:)`, still in
`SwiftDocCUtilities`, where they are written into the global feature flags ``FeatureFlags/current``
`CommandLine`, where they are written into the global feature flags ``FeatureFlags/current``
instance, which can then be used during the compilation process.

### Feature flags in Info.plist
Expand All @@ -37,4 +37,4 @@ Feature flags that are loaded from an Info.plist file are saved into the global
the bundle is being registered. To ensure that your new feature flag is properly loaded, update the
``FeatureFlags/loadFlagsFromBundle(_:)`` method to load your new field into the global flags.

<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->
<!-- Copyright (c) 2024-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ SwiftDocC.docc
├ Essentials
│ ├ ActionManager.md
│ ├ Action.md
│ ╰ Getting Started with SwiftDocCUtilities.md
│ ╰ Getting Started with SwiftDocC.md
├ Migration to DocC
│ ├ DocumentationContext.md
│ ╰ ...
Expand Down Expand Up @@ -104,4 +104,4 @@ The file hierarchy under the output path represents the complete, compiled docum
╰ videos
```

<!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->
<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->
4 changes: 2 additions & 2 deletions Sources/SwiftDocCUtilities/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
#]]

add_library(SwiftDocCUtilities STATIC
add_library(CommandLine STATIC
Action/Action.swift
Action/ActionResult.swift
Action/Actions/Action+MoveOutput.swift
Expand Down Expand Up @@ -69,6 +69,6 @@ add_library(SwiftDocCUtilities STATIC
Utility/PlatformArgumentParser.swift
Utility/Signal.swift
Utility/Throttle.swift)
target_link_libraries(SwiftDocCUtilities PUBLIC
target_link_libraries(CommandLine PUBLIC
ArgumentParser
SwiftDocC)
2 changes: 1 addition & 1 deletion Sources/docc/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ See https://swift.org/LICENSE.txt for license information
add_executable(docc
main.swift)
target_link_libraries(docc PRIVATE
SwiftDocCUtilities)
CommandLine)

install(TARGETS docc
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
4 changes: 2 additions & 2 deletions Sources/docc/main.swift
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
*/

#if os(macOS) || os(Linux) || os(Android) || os(Windows) || os(FreeBSD)
import SwiftDocCUtilities
import CommandLine

await Task {
await Docc.main()
Expand Down
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2022 Apple Inc. and the Swift project authors
Copyright (c) 2022-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
*/

import XCTest
@testable import SwiftDocCUtilities
@testable import CommandLine
@testable import SwiftDocC
import SwiftDocCTestUtilities
import TestUtilities
import ArgumentParser

class ConvertSubcommandSourceRepositoryTests: XCTestCase {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
*/

import XCTest
@testable import SwiftDocCUtilities
@testable import CommandLine
@testable import SwiftDocC
import SwiftDocCTestUtilities
import TestUtilities

class ConvertSubcommandTests: XCTestCase {
private let testBundleURL = Bundle.module.url(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2021 Apple Inc. and the Swift project authors
Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
Expand All @@ -10,7 +10,7 @@

import XCTest
import Foundation
@testable import SwiftDocCUtilities
@testable import CommandLine

class ErrorMessageTests: XCTestCase {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@

import XCTest
import ArgumentParser
@testable import SwiftDocCUtilities
import SwiftDocCTestUtilities
@testable import CommandLine
import TestUtilities

class MergeSubcommandTests: XCTestCase {
func testCommandLineArgumentValidation() throws {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2021 Apple Inc. and the Swift project authors
Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
Expand All @@ -10,7 +10,7 @@

#if canImport(NIOHTTP1)
import XCTest
@testable import SwiftDocCUtilities
@testable import CommandLine

class PreviewSubcommandTests: XCTestCase {
func testOptionsValidation() throws {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
import XCTest
import Foundation
@testable import SwiftDocC
@testable import SwiftDocCUtilities
@testable import CommandLine

class ConvertActionIndexerTests: XCTestCase {

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
Expand All @@ -11,8 +11,8 @@
import XCTest
import Foundation
@testable import SwiftDocC
@testable import SwiftDocCUtilities
import SwiftDocCTestUtilities
@testable import CommandLine
import TestUtilities

class ConvertActionStaticHostableTests: StaticHostingBaseTests {
/// Creates a DocC archive and then archives it with options to produce static content which is then validated.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@
import XCTest
import Foundation
@testable @_spi(ExternalLinks) import SwiftDocC
@testable import SwiftDocCUtilities
@testable import CommandLine
import SymbolKit
import Markdown
@testable import SwiftDocCTestUtilities
@testable import TestUtilities

class ConvertActionTests: XCTestCase {
#if !os(iOS)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
*/

import XCTest
@testable import SwiftDocCUtilities
@testable import CommandLine

#if !os(Linux) && !os(Android) && !os(Windows) && !os(FreeBSD)
fileprivate extension NSNotification.Name {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2024 Apple Inc. and the Swift project authors
Copyright (c) 2024-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
Expand All @@ -10,8 +10,8 @@

import XCTest
import Foundation
@testable import SwiftDocCUtilities
import SwiftDocCTestUtilities
@testable import CommandLine
import TestUtilities

class EmitGeneratedCurationsActionTests: XCTestCase {

Expand Down
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
*/

@testable import SwiftDocC
@testable import SwiftDocCUtilities
@testable import CommandLine
import XCTest
public import SwiftDocCTestUtilities
public import TestUtilities

/*
This file contains a test helper API for working with folder hierarchies, with the ability to:
Expand Down
Loading