Skip to content
Prev Previous commit
Next Next commit
Add prefix to target names in comments and scripts
  • Loading branch information
d-ronnqvist committed Nov 14, 2025
commit 62d4c53ae0207e6b30e7d5071d36b6c13ce8c369
2 changes: 1 addition & 1 deletion 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/)
- [`CommandLine` framework documentation](https://swiftlang.github.io/swift-docc/documentation/commandline/)
- [`DocCCommandLine` framework documentation](https://swiftlang.github.io/swift-docc/documentation/docccommandline/)

### Related Projects

Expand Down
2 changes: 1 addition & 1 deletion Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ let package = Package(
swiftSettings: swiftSettings
),

// Test app for CommandLine
// Test app for DocCCommandLine
.executableTarget(
name: "signal-test-app",
dependencies: [
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(CommandLine)
add_subdirectory(DocCCommandLine)
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 CommandLine, because SwiftDocC doesn't link against ArgumentParser (since it isn't about CLI).
// These conforming types are defined in SwiftDocC and extended in DocCCommandLine, 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
4 changes: 2 additions & 2 deletions Sources/DocCCommandLine/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(CommandLine STATIC
add_library(DocCCommandLine STATIC
Action/Action.swift
Action/ActionResult.swift
Action/Actions/Action+MoveOutput.swift
Expand Down Expand Up @@ -69,6 +69,6 @@ add_library(CommandLine STATIC
Utility/PlatformArgumentParser.swift
Utility/Signal.swift
Utility/Throttle.swift)
target_link_libraries(CommandLine PUBLIC
target_link_libraries(DocCCommandLine PUBLIC
ArgumentParser
SwiftDocC)
6 changes: 3 additions & 3 deletions Sources/DocCCommandLine/CommandLine.docc/CommandLine.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# ``CommandLine``
# ``DoCCCommandLine``

Build custom documentation workflows by leveraging the DocC compiler pipeline.

## Overview

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.
DocCCommandLine 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 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``.
Use DocCCommandLine 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
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 `CommandLine`.
Command-line feature flags live in the `Docc.Convert.FeatureFlagOptions` in `DocCCommandLine`.
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
`CommandLine`, where they are written into the global feature flags ``FeatureFlags/current``
`docCCommandLine`, 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 Down
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
CommandLine)
DocCCommandLine)

install(TARGETS docc
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
2 changes: 1 addition & 1 deletion Tests/signal-test-app/main.swift
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

//
// Trap signals and exit with a predefined error code.
// Check Tests/CommandLineTests/SignalTests.swift for more details.
// Check Tests/DocCCommandLineTests/SignalTests.swift for more details.
//

#if os(macOS) || os(Linux) || os(Android)
Expand Down
2 changes: 1 addition & 1 deletion bin/check-source
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ for language in swift-or-c bash md-or-tutorial html docker; do
reader=head
case "$language" in
swift-or-c)
exceptions=( -name Package.swift -o -path "./Tests/SwiftDocCTests/Test Bundles/*" -o -path "./Tests/CommandLineTests/Test Bundles/*")
exceptions=( -name Package.swift -o -path "./Tests/SwiftDocCTests/Test Bundles/*" -o -path "./Tests/DocCCommandLineTests/Test Bundles/*")
matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
cat > "$tmp" <<"EOF"
/*
Expand Down
16 changes: 8 additions & 8 deletions bin/preview-docs
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ while test $# -gt 0; do
case "$1" in
--help)
echo
echo "Usage: $(basename $0) [SwiftDocC|CommandLine|DocC] [-h] [--convert-only]"
echo "Usage: $(basename $0) [SwiftDocC|DocCCommandLine|DocC] [-h] [--convert-only]"
echo "Builds the given framework and converts or previews the documentation"
echo "Note: To preview you must set the \`DOCC_HTML_DIR\` with a path to a documentation template.

Expand Down Expand Up @@ -80,24 +80,24 @@ case $FRAMEWORK in
--output-path "$DOCS_BUILD_DIR"
;;

"CommandLine")
"DocCCommandLine")

# Generate symbol graph files for CommandLine
# Generate symbol graph files for DocCCommandLine
swift build --package-path "$DOCC_ROOT" \
--target CommandLine \
--target DocCCommandLine \
-Xswiftc -emit-symbol-graph \
-Xswiftc -emit-symbol-graph-dir -Xswiftc "$SGFS_DIR"

echo

# Delete the symbol graph files from dependences by looking for
# those without a 'CommandLine' prefix.
find "$SGFS_DIR" -type f ! -name 'CommandLine*' -delete
# those without a 'DocCCommandLine' prefix.
find "$SGFS_DIR" -type f ! -name 'DocCCommandLine*' -delete

echo

# Compile the documentation and the symbol graph data.
swift run docc $DOCC_CMD "$DOCC_ROOT/Sources/CommandLine/CommandLine.docc" \
swift run docc $DOCC_CMD "$DOCC_ROOT/Sources/DocCCommandLine/CommandLine.docc" \
--experimental-enable-custom-templates \
--fallback-display-name CommandLine \
--fallback-bundle-identifier org.swift.CommandLine \
Expand All @@ -116,7 +116,7 @@ case $FRAMEWORK in

*)
echo
echo "Error: Unknown module '$FRAMEWORK'. Preview is supported only for SwiftDocC, CommandLine, or DocC."
echo "Error: Unknown module '$FRAMEWORK'. Preview is supported only for SwiftDocC, DocCCommandLine, or DocC."
exit 0
;;
esac
8 changes: 4 additions & 4 deletions bin/update-gh-pages-documentation-site
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ SWIFT_DOCC_ROOT="$(dirname $(dirname $(filepath $0)))"

DOCC_BUILD_DIR="$SWIFT_DOCC_ROOT"/.build/docc-gh-pages-build
DOCC_OUTPUT_DIR="$DOCC_BUILD_DIR"/SwiftDocC.doccarchive
COMMAND_LINE_OUTPUT_DIR="$DOCC_BUILD_DIR"/CommandLine.doccarchive
COMMAND_LINE_OUTPUT_DIR="$DOCC_BUILD_DIR"/DocCCommandLine.doccarchive

mkdir -p "$COMMAND_LINE_OUTPUT_DIR"

Expand Down Expand Up @@ -60,12 +60,12 @@ swift package \

echo -e "\033[34;1m Building SwiftDocC Utilities docs at $COMMAND_LINE_OUTPUT_DIR \033[0m"

# Generate documentation for the 'CommandLine' target and output it
# Generate documentation for the 'DocCCommandLine' target and output it
# to a temporary output directory in the .build directory.
swift package \
--allow-writing-to-directory "$DOCC_BUILD_DIR" \
generate-documentation \
--target CommandLine \
--target DocCCommandLine \
--disable-indexing \
--source-service github \
--source-service-base-url https://github.com/swiftlang/swift-docc/blob/main \
Expand All @@ -79,7 +79,7 @@ echo -e "\033[34;1m Merging docs \033q[0m"
# Remove the output directory so that the merge command can output there
rm -rf "$SWIFT_DOCC_ROOT/gh-pages/docs"

# Merge the CommandLine docs into the primary SwiftDocC docs
# Merge the DocCCommandLine docs into the primary SwiftDocC docs
swift run docc merge \
"$DOCC_OUTPUT_DIR" \
"$COMMAND_LINE_OUTPUT_DIR" \
Expand Down